|
libfossil
|
The fsl_sc class encapsulates a streamable (as opposed to random-access) I/O channel intended solely for use in implementing fossil(1)'s sync protocol in libfossil in an I/O-channel-agnostic manner. More...
#include "sync.h"
Data Fields | |
| int(* | append )(fsl_sc *ch, void const *pIn, fsl_size_t n) |
| Must append the first n bytes of pIn to the outbound sync request payload. | |
| void(* | cleanup )(fsl_sc *ch) |
| Must free up all dynamically-allocated resources owned by ch and ch->impl. | |
| fsl_flag32_t | flags |
| Flags for customizing certain behaviors. | |
| struct { | |
| void * p | |
| Arbitrary state for implementations. More... | |
| void const * type | |
| An optional value which uniquely identifies with a specific type. More... | |
| } | impl |
| Implementation-dependent state. | |
| int(* | init )(fsl_sc *ch, enum fsl_sc_init_e mode) |
| This callback's responsibility is to initialize and validate any resources which may be implied via this->impl. | |
| char const * | name |
| A debugging-purposes name for this channel, e.g. | |
| int(* | read )(fsl_sc *ch, fsl_buffer *tgt, fsl_int_t howMuch) |
| fsl_buffer | requestHeaders |
| If this->flags contains FSL_SC_F_REQUEST_HEADERS, the library will populate this with raw HTTP headers for the request, including a trailing \r\n line, immediately before calling submit(). | |
| fsl_buffer | scratch |
| A general-purpose scratchpad buffer for use by the channel object and the library internals. | |
| fsl_sc *(* | self )(fsl_sc *ch) |
| int(* | submit )(fsl_sc *ch, fsl_buffer const *loginCard) |
| Tells the channel that the library is done building the request payload and it should be submitted. | |
| fsl_url | url |
| The remote fossil URL. | |
| fsl_xfer * | xfer |
| The "transfer context" for this channel. | |
The fsl_sc class encapsulates a streamable (as opposed to random-access) I/O channel intended solely for use in implementing fossil(1)'s sync protocol in libfossil in an I/O-channel-agnostic manner.
(Thus the name "sc" - an abbreviation of "sync channel".) The idea is that we can hook up arbitrary streamable I/O channels via this interface, e.g. HTTP-, SSH-, and file-driven channels.
Each instance must be fully populated to set up its fsl_cx, I/O methods, and non-NULL values for all requires methods (init(), cleanup(), etc.). Each instance may have arbitrary state associated with it, but whether such state must be provided by the user, or is created/initialized by the open() implementation, is implementation-defined.
A channel's lifecycle, in terms of its API, goes something like:
Open design issues:
| int(* fsl_sc::append) (fsl_sc *ch, void const *pIn, fsl_size_t n) |
Must append the first n bytes of pIn to the outbound sync request payload.
The library will call this an arbitrary number of times to generate the sync body payload.
Implementations are free to buffer, or not, the payload, depending on their requirements, but practical considerations may make buffering unavoidable. e.g. an HTTP implementation will require the full payload before sending, so that the Content-Size header can be set and the headers pushed before the payload is. A streaming-to-(FILE*) implementation, however, has no such requirements, so could avoid an extra buffering step (unless, perhaps, that file's contents are intended for further processing by, e.g., netcat(1), in which case HTTP headers would need to be prepended).
Achtung: calling this API directly from client code will effectively corrupt the output. The library internals funnel all fsl_sc output traffic through a single point so that the size of the request and its SHA1 hash can be kept track of (both are needed for sending authenticated requests). Calling this API directly will bypass that and result in request bodies whose hashes do not match fossil's authentication expectations.
| void(* fsl_sc::cleanup) (fsl_sc *ch) |
Must free up all dynamically-allocated resources owned by ch and ch->impl.
Finalizing must, if appropriate, free up any resources it uses, but must not free the object passed to it (which might be stack-allocated or part of a larger struct). If this connection is still open, it must close it.
It is up to the implementation to set ch->impl.p to 0 if that's appropriate for them - the library does not do so. Some implementations may use static state and not need to reset ch->impl.
In the wisdom of "destructors must not throw," the library provides no way to report a failure to close a channel (nor does it really care, at that point - by then the channel will have either already failed or served its purpose). If, after this call, ch->f has error state, the library has the option, at its developers' discretion, of emitting a warning to the client (this is unspecified and currently unimplemented, but warning and/or debug channels may be added at some point).
The library will never pass NULL to this function.
The library does not guaranty that a db transaction will be in place when this is called.
This method must never be called directly from client code. Instead, pass the object to fsl_sc_cleanup(), as that will free up the common fsl_sc members, leaving clean() impls to only concern themselves with their own private state.
| fsl_flag32_t fsl_sc::flags |
| struct { ... } fsl_sc::impl |
Implementation-dependent state.
| int(* fsl_sc::init) (fsl_sc *ch, enum fsl_sc_init_e mode) |
This callback's responsibility is to initialize and validate any resources which may be implied via this->impl.
The second argument tells the implementation what type of initialization is required, as per the fsl_sc_init_e docs.
FSL_SC_INIT_INITIAL is only ever passed one time per object and is guaranteed to be called before FSL_SC_INIT_REQUEST is. If the channel needs to perform any validation, that is the time to do is.
FSL_SC_INIT_REQUEST is called each time a new request body needs to be generated. Implementations must discard any prior request-specific state when initialized with this value.
ch->flags must be set before calling this and must not be modified afterwards. The library will set the ch->xfer member.
It is up to the direct users of this API to ensure that their fsl_sc instances contain no randomly-initialized state before the initial call to this function.
This call may, depending on the impl, initialize ch->impl, whereas some channel implementations may require that the caller populate ch->impl with an implementation-defined "something". Those details are to be documented for each concrete implementation.
Implementations must return 0 on success. On error they must return a fsl_rc_e value and should ideally use fsl_xfer_error() on ch->xfer to report an error message.
The library guarantees that a db transaction will be in effect when it calls this function, and that failure from any fsl_sc API will be propagated back and cause the transaction to roll back.
Regardless of success or failure, clients are required to eventually call the cleanup() method if they call init(). On a failed init() call, it is not generically knowable whether it's okay to call init() again, and clients should not do so.
Whether or not this step will initialize any network and/or FILE and/or RPC connections is left to the implementation. It may do so here, if needed, or it may delay such things until submit().
| char const* fsl_sc::name |
| void* fsl_sc::p |
| int(* fsl_sc::read) (fsl_sc *ch, fsl_buffer *tgt, fsl_int_t howMuch) |
Must read, or consume from its buffer, the requested amount of
data and append it to tgt. It must only append to the target
buffer, not reset or otherwise manipulate it, as the buffer may
already contain state when this is called.
If howMuch is greater than zero, it's a number of bytes which are
expected to be appended to tgt. A non-0 result code must be
returned if exactly that many bytes cannot be consumed.
If howMuch is FSL_SC_READ_LINE then:
1) One newline-separated (0x0A) line must read from the input
source and be append to tgt, including the newline character.
Aside from interpretation of that one character,
implementations must treat the preceeding data (if any) as
opaque. i.e. it must not be otherwise parsed and empty lines
must not be skipped.
2) If no newline is found, return FSL_RC_BREAK if at EOF and no
data precedes the EOF, else some other non-0 error code
(e.g. FSL_RC_IO). The library will interpret FSL_RC_BREAK as a
non-error EOF condition.
If howMuch is FSL_SC_READ_ALL then the library must read the
whole response into the target buffer. (This is used by the
library to handle fossil-compressed response bodies on behalf of
fsl_sc implementations.) If the implementation internally stores
the response in fsl_buffer, it should use fsl_buffer_swap() to
transfer it to tgt, rather than copy it. If it uses a file,
fsl_stream() can be used to transfer it, e.g.:
```
fsl_stream(fsl_input_f_FILE, responseFile,
fsl_output_f_buffer, tgt);
or: fsl_stream(fsl_input_f_fd, &myFileDescriptor, fsl_output_f_buffer, tgt); ```
When howMuch is FSL_SC_READ_ALL, the library will not read any more from the channel until/unless ch->submit() is called again, so the implementation may free up any related resources at that point if it likes.
The library will never pass a howMuch value of 0 to this function, but it reserves the option of eventually using 0 as a way of communicating that we are done reading, if such a capability ever becomes useful. For future compatibility's sake, it's legal to simply return 0 if howMuch is 0, but it's also legal to assert(howMuch!=0) until that happens.
Must return 0 on success, non-0 on error, and should use one of the fsl_xfer_error() family of functions to to provide any error message and propagate the error through the library.
| fsl_buffer fsl_sc::requestHeaders |
If this->flags contains FSL_SC_F_REQUEST_HEADERS, the library will populate this with raw HTTP headers for the request, including a trailing \r\n line, immediately before calling submit().
Implementations' submit() methods must, unless they do their own header generation, emit this before the body. See FSL_SC_F_REQUEST_HEADERS.
| fsl_buffer fsl_sc::scratch |
This is internal-use tooling to support adding "shim" layers of fsl_sc between the library and the "real" fsl_sc. The default impl (fsl_sc_self()) is suitable for all non-proxying channels and simply returns its argument. The impl for the tracer channel returns the object it's tracing. This distinction is relevant for handing of fsl_sc internals such as ch->url and ch->flags, in that (A) the internals always want those values to come from the "real" implementation, not the shim, and (B) they don't want code which is using a shim to have to know it's using a shim. Calling ch->self(ch)->url will return the "correct" URL object. Implementation code of a fsl_sc, unless that channel is itself a proxy for another, should not use this - it's simply not needed there. It's used by library code which wants to avoid having to know there's a shim/proxy channel in place. Implementors of proxy channels must provide a self() implementation which looks something like the following (taken from the tracer channel): ```
Custom channel state, set in fsl_sc::impl.p of channels of this subtype. struct my_channel_state { fsl_sc * proxied; // proxied channel ... any other necessary state ... }; typedef struct my_channel_state my_channel_state;
fsl_sc * my_self(fsl_sc *ch){ my_channel_state * const st = ch->impl.p; fsl_sc * const orig = st->proxied; return orig->self(orig); // call self() in case orig is a proxy! } ```
| int(* fsl_sc::submit) (fsl_sc *ch, fsl_buffer const *loginCard) |
Tells the channel that the library is done building the request payload and it should be submitted.
If this method buffers its response, it may close (if still opened) any channel opened by init() but should retain any state which might be needed for reestablishing that connection. If it does not buffer the response, it may keep the channel open for downstream read() calls.
This is never called before init() is passed FSL_SC_INIT_REQUEST and is never called when any call to init() fails.
If loginCard is not NULL, it contains the full content of a login card for the request. Implementations must emit these bytes as an HTTP header in this form:
Which, in C, might look something like:
(Sidebar: that approach to authentication only works with fossil versions newer than 2025-07-27, so the library cannot log in to older fossil versions but can otherwise speak to them.)
The library guarantees that the same db transaction as was in effect when ch->init() was called will be in place when this is called.
Implementations must return 0 on success. On error, implementations must return a non-FSL_RC_OK value from the fsl_rc_e enum, and are strongly encouraged to set an error message using the fsl_xfer_error() family of functions, passing ch->xfer to it.
| void const* fsl_sc::type |
| fsl_url fsl_sc::url |
The remote fossil URL.
It is up to the client to either set up the URL before passing this object on to the library or to ensure that the last-sync-url is of a schema compatible with this instance.
It is also up to the client to ensure that the URL scheme matches the fsl_sc implementation. How best to do that is still TBD.
This memory is owned by this object.
| fsl_xfer* fsl_sc::xfer |