3#if !defined(ORG_FOSSIL_SCM_FSL_SYNC_H_INCLUDED)
4#define ORG_FOSSIL_SCM_FSL_SYNC_H_INCLUDED
24#if defined(__cplusplus)
102#define fsl_xfer_dbg_empty_m {.callback=0, .state=0, .b=fsl_buffer_empty_m}
212#define FSL_SC_READ_LINE ((fsl_int_t)-1)
219#define FSL_SC_READ_ALL ((fsl_int_t)-2147483648)
655#define fsl_sc_empty_m { \
656 .xfer=0, .name="unnamed", \
657 .url=fsl_url_empty_m, \
659 .impl = {.p = 0,.type = 0}, \
660 .init=0, .append = 0, \
662 .read=0, .cleanup=0, \
664 .requestHeaders = fsl_buffer_empty_m, \
665 .scratch = fsl_buffer_empty_m \
676 FSL_SYNC_PUSH = 1<<0,
677 FSL_SYNC_PULL = 1<<1,
678 FSL_SYNC_BIDI = FSL_SYNC_PUSH | FSL_SYNC_PULL,
679 FSL_SYNC_CLONE = 1<<2,
680 FSL_SYNC_PRIVATE = 1<<3,
681 FSL_SYNC_VERBOSE = 1<<4,
682 FSL_SYNC_RESYNC = 1<<5,
683 FSL_SYNC_DEBUG = 1<<6,
684 FSL_SYNC_DRYRUN = 1<<7,
685 FSL_SYNC_AUTO = 1<<8,
1095#define fsl_sc_popen_state_init(BinName,xInit,XCmdInit,XCleanup) { \
1098 .buildCommandLine=XCmdInit, \
1099 .cleanup=XCleanup, .state = 0 \
1101 .bin = { .name = BinName, .location = 0 }, \
1103 .fStdIn = 0, .fdStdOut = -1, .pid = 0 \
1106 .filename = 0, .fp = 0, .count=0 \
1109 .mode = fsl_sc_popen_e_default, \
1110 .filename = 0, .fp = 0, .fd = -1, \
1111 .count=0, .b = fsl_buffer_empty_m \
1115 .tmpfilePrefix = 0 \
1117 .cmd = fsl_buffer_empty_m \
1234#define fsl_sc_tracer_map(E) \
1236 E(init,1) E(read, 1<<1) E(append, 1<<2) \
1237 E(cleanup, 1<<3) E(submit, 1<<4) E(self, 1<<5) \
1241#define E(NAME,FLAG) FSL_SC_TRACER_ ## NAME = FLAG,
1245 FSL_SC_TRACER_all = 0
1246#define E(NAME,FLAG) | FSL_SC_TRACER_ ## NAME
1251 | FSL_SC_TRACER_cleanup
1252 | FSL_SC_TRACER_submit
1253 | FSL_SC_TRACER_self
1306#define fsl_xfcard_map(E) \
1307 E(cfile,5) E(clone,5) E(clone_seqno,11) E(config,6) \
1308 E(cookie,6) E(error,5) E(file,4) E(gimme,5) E(igot,4) \
1309 E(login,5) E(uvfile,6) E(message,7) E(pragma,6) \
1310 E(private,7) E(pull,4) E(push,4) E(reqconfig,9) \
1311 E(uvgimme,7) E(uvigot,6)
1322#define E(T,LEN) fsl_xfcard_e_ ## T,
1334#define fsl_xfcard_zeroes \
1335 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
1418#define fsl_xfer_metrics_empty_m { \
1427 .danglingFile = 0, \
1428 .rcvdArtifacts = 0, \
1431 .largestCardPayload = 0, \
1432 .largestDecompressedResponse = 0, \
1433 .bytesReadCompressed = 0, \
1434 .bytesReadUncompressed = 0, \
1435 .bytesWritten = 0, \
1436 .cardsRx = {fsl_xfcard_zeroes}, \
1437 .cardsTx = {fsl_xfcard_zeroes}, \
1439 .read = fsl_timer_empty_m, \
1440 .submit = fsl_timer_empty_m, \
1441 .uncompress = fsl_timer_empty_m, \
1442 .process = fsl_timer_empty_m \
1474 void *state,
int theRc);
1547int fsl_pw_f_getpass(
fsl_cx * f,
char const * zUrl,
1689#define fsl_xfer_config_empty_m { \
1691 .maxResponseSeconds = -1, \
1692 .maxResponseBytes = 2500000, \
1694 .compressTraffic=false, \
1695 .listener = fsl_msg_listener_empty_m, \
1696 .debug = fsl_xfer_dbg_empty_m, \
1699 .outputer = fsl_outputer_FILE_m \
1705 .privateContent = false, \
1709 .callback = NULL, .state = NULL \
1749#define fsl_clone_config_empty_m { \
1750 .repo = fsl_repo_create_opt_empty_m, \
1751 .xfer = fsl_xfer_config_empty_m \
1780fsl_sc * fsl_sc_for_url(
char const * zUrl );
1783#if defined(__cplusplus)
uint64_t fsl_size_t
fsl_size_t is an unsigned integer type used to denote absolute ranges and lengths.
uint32_t fsl_flag32_t
A 32-bit unsigned int type.
int64_t fsl_int_t
fsl_int_t is a signed integer type used to denote "relative" ranges and lengths, or to tell a routine...
This file declares the core SCM-related public APIs.
struct fsl__xfer fsl_xfer
A "transfer context" type used by many of the sync transfer APIs.
repo.h declares APIs specifically dealing with repository-db-side state, as opposed to specifically c...
A general-purpose buffer class, analog to Fossil's Blob class, but it is not called fsl_blob to avoid...
Options for use with fsl_clone().
fsl_xfer_config xfer
Options related to the transfer subsystem.
fsl_repo_create_opt repo
Options for fsl_repo_create().
The main Fossil "context" type.
A container for storing generic error state.
Client callback info for receiving various events during fossil sync processing.
An interface which encapsulates data for managing an output destination, primarily intended for use w...
Configuration parameters for fsl_repo_create().
State for use with the fsl_sc_popen fsl_sc impl.
struct fsl_sc_popen_state::@047271017132162232375350103101020026106103313371 impl
State for "subclasses".
FILE * fp
Request payload temp file.
char * filename
Filename of this->fp.
FILE * fStdIn
The external process's stdin, i.e.
int(* init)(fsl_sc *ch)
This optional method gets called as part of the FSL_SC_INIT_INITIAL phase of fsl_sc::init() to give s...
void * allocStamp
Internal implementation detail.
struct fsl_sc_popen_state::@266006325223237141160063003276124156214251367351 bin
Info about the binary.
unsigned count
Number of initiated requests.
int(* buildCommandLine)(fsl_sc *ch, fsl_buffer *b, fsl_buffer const *bLoginCard)
Command arguments initializer.
char * tmpfilePrefix
A random prefix for temp file names.
struct fsl_sc_popen_state::@121130223373173160053065235325045114363362012212 process
State for/around fsl__popen2().
fsl_buffer b
Response body when this->mode is fsl_sc_popen_e_membuf.
struct fsl_sc_popen_state::@066143155145161020053303036043160147002317037320 request
State for the sync request payload.
void * state
Subclass-specific state.
void(* cleanup)(fsl_sc_popen_state *st)
May be set for subclasses in order to clean up any dynamic state owned by this object in this->impl....
char const * name
The name of the program binary, e.g.
fsl_buffer cmd
The command line to invoke.
char * location
Location where the binary was found.
int fd
Response input source when this->mode is fsl_sc_popen_e_fd.
int fdStdOut
The external process's stdout, i.e.
struct fsl_sc_popen_state::@146344352027260375167101145077256277014053205264 misc
Flag(s).
int pid
The external process's PID.
struct fsl_sc_popen_state::@160202264027050270357317003235201000205071030176 response
State for the sync response payload.
enum fsl_sc_popen_e mode
How to read the response.
The fsl_sc class encapsulates a streamable (as opposed to random-access) I/O channel intended solely ...
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.
int(* read)(fsl_sc *ch, fsl_buffer *tgt, fsl_int_t howMuch)
fsl_buffer scratch
A general-purpose scratchpad buffer for use by the channel object and the library internals.
struct fsl_sc::@141212271130253270352243142255342306302133242340 impl
Implementation-dependent state.
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.
void const * type
An optional value which uniquely identifies with a specific type.
fsl_xfer * xfer
The "transfer context" for this channel.
char const * name
A debugging-purposes name for this channel, e.g.
fsl_buffer requestHeaders
If this->flags contains FSL_SC_F_REQUEST_HEADERS, the library will populate this with raw HTTP header...
void(* cleanup)(fsl_sc *ch)
Must free up all dynamically-allocated resources owned by ch and ch->impl.
void * p
Arbitrary state for implementations.
fsl_flag32_t flags
Flags for customizing certain behaviors.
fsl_url url
The remote fossil URL.
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 t...
State for the fsl_timer_xxx() family of functions.
Various configuration pieces for libfossil sync transfer subsystem.
fsl_msg_listener listener
When a sync operation happens on a transient fs_cx instance, e.g.
bool leaveTempFiles
A hint for fsl_sc channels which support it.
int32_t maxResponseBytes
NYI!
void * state
Optional state for the 2nd argument to this->callback().
char const * url
The URL or filename to sync with.
struct fsl_xfer_config::@373075157177271020150144310017273005255063000152 trace
fsl_sc API tracing hook.
fsl_outputer outputer
The output sink.
fsl_xfer_dbg debug
Optional debug message callback.
struct fsl_xfer_config::@064076272252252201345077146365363164074334354076 metrics
bool compressTraffic
If true, use the application/x-fossil-uncompressed Content-Type for communication,...
short verbosity
Verbosity level (higher is more verbose).
int8_t maxResponseSeconds
NYI!
struct fsl_xfer_config::@376254203134267303377005241154115036357014055045 password
fsl_xfer_metrics_f callback
If not NULL, fsl__xfer's cleanup routine will call this, passing it the metrics, this->state,...
struct fsl_xfer_config::@330375130000151220245243240067014303307134273010 op
Members which are set to true will activate specific aspects of sync.
fsl_flag32_t mask
If non-zero, a tracing channel is installed with the given mask of fsl_sc_tracer_e flags.
Internal part of fsl_sc, uplifted into its own struct to simplify proper intialization of them in dow...
void * state
Available in callback() implementations via ch->debug.state.
fsl_buffer b
This is a scratch buffer solely for internal use by:
fsl_xfer_dbg_f callback
This optional method is intended to be set by client-level code, not the sync channel implementor.
Metrics for use with the library's "xfer" (sync) subsystem.
fsl_size_t largestDecompressedResponse
Buffer capacity allocated for the latest single fossil-compressed response.
fsl_size_t sentCards
Total sent cards.
fsl_size_t cardsRx[fsl_xfcard_e_COUNT]
Counts of each card type seen in the response(s).
fsl_size_t deltaRcvd
Number of deltas received.
fsl_timer uncompress
Time taken to decompress cfile card payloads.
fsl_timer read
Time spent waiting on fsl_sc::read(), but only via fsl__xfer_read(), fsl__xfer_readln(),...
fsl_size_t deltaSent
Number of deltas sent.
fsl_size_t fileRcvd
Number of files received.
fsl_size_t largestCardPayload
Largest card payload size.
fsl_size_t bytesWritten
Number of bytes via fsl__xfer_append() and friends.
fsl_size_t cardsTx[fsl_xfcard_e_COUNT]
Counts of each card type sent in request(s).
fsl_size_t danglingFile
Number of dangling deltas received.
fsl_size_t privIGot
Number of private "igot" cards.
fsl_timer submit
Time spent waiting on fsl_sc::submit().
fsl_size_t rcvdCards
Total received cards.
fsl_size_t rcvdArtifacts
Total received artifacts.
fsl_timer process
Time taken to decompress cfile card payloads.
fsl_size_t fileSent
Number of files sent.
fsl_size_t iGotSent
Number of "igot" cards sent.
fsl_size_t gimmeSent
Number of gimme cards sent.
fsl_size_t trips
Number of connections made to the remote.
struct fsl_xfer_metrics::@015053054177105240360335110365176034324057100222 timer
Various timing metrics.
fsl_size_t bytesReadUncompressed
Number of uncompressed response bytes via fsl__xfer_read() and fsl_xfer_readln().
fsl_size_t bytesReadCompressed
Number of compressed response bytes via fsl__xfer_submit().
FSL_EXPORT void fsl_xfer_debug_f_FILE(fsl_xfer *xf, char const *zMsg)
An implementation for fsl_xfer::debug::callback which requires that the associated state be a (FILE*)...
FSL_EXPORT void fsl_sc_cleanup(fsl_sc *ch)
Calls fsl_sc_close() then, if ch->cleanup is not NULL, it is called.
void(* fsl_xfer_dbg_f)(fsl_xfer *xf, char const *zMsg)
Callback for xfer-layer debugging messages.
#define fsl_xfcard_map(E)
const fsl_sc fsl_sc_popen_ssh
Works like fsl_sc_popen_curl but uses "ssh ... fossil test-http" for the transport layer.
FSL_EXPORT fsl_cx * fsl_xfer_cx(fsl_xfer *xf)
Returns xf's fsl_cx context.
FSL_EXPORT fsl_sc * fsl_sc_self(fsl_sc *ch)
The default implementation of fsl_sc::self().
FSL_EXPORT int fsl_sync_client(fsl_cx *f,...)
NOT YET IMPLEMENTED.
int fsl_clone(fsl_clone_config const *cc, fsl_error *err)
Under construction.
const fsl_sc fsl_sc_empty
Empty-initialized fsl_sc instance, intended for copy initialization.
#define fsl_sc_tracer_map(E)
Expands to a mapping of all fsl_sc_tracer_e types by invoking E(NAME,VALUE) for each one.
int(* fsl_pw_f)(fsl_cx *f, char const *zUrl, fsl_buffer *bOut, void *state)
This typedef describes a callback used by the library for fetching passwords when needed for remote s...
fsl_sc_F_lib_e
Flags for use with fsl_sc::flags.
@ FSL_SC_F_lib_mask
The mask of FSL_SC_F_... bits which are reserved for use by library-level options.
@ FSL_SC_F_COMPRESSED
Tells the fsl_sc impl that it should post data using the HTTP Content-Type value of "application/x-fo...
@ FSL_SC_F_REQUEST_HEADERS
For impls with this flag set, the library will populate their fsl_sc::requestHeaders immediately befo...
@ FSL_SC_F_client_mask
The mask of FSL_SC_F_... bits which are reserved for use by client-level options.
@ FSL_SC_F_SUPPRESS_STDERR
Impls which might, due to shelling out, emit info to stderr are expected to honor this flag and redir...
@ FSL_SC_F_LEAVE_TEMP_FILES
Impls which use temp files must honor this flag by not deleting those files, so that they can be exam...
fsl_sc_init_e
Initialization modes for use with fsl_sc::init() implementations.
@ FSL_SC_INIT_REQUEST
Indicates that the object must (re)initialize any state needed for constructing a request.
@ FSL_SC_INIT_INITIAL
Indicates that the fsl_sc instance should initialize any core resources but not any request/response ...
const fsl_clone_config fsl_clone_config_empty
Empty-initialized fsl_clone_config instance intended for non-const-copy initialization.
const fsl_xfer_config fsl_xfer_config_empty
Empty-initialized fsl_xfer_config instance intended for non-const-copy initialization.
const fsl_xfer_metrics fsl_xfer_metrics_empty
Empty-initialized fsl_xfer_metrics instance intended for non-const copy initialization.
const fsl_sc fsl_sc_popen
An empty base fsl_sc instance for use with fsl_sc_popen_state implementations.
const fsl_sc_popen_state fsl_sc_popen_state_ssh
State type for use with fsl_sc_popen_ssh.
const fsl_sc fsl_sc_popen_fth
Works like fsl_sc_popen_curl but uses "fossil test-http" for the transport layer.
fsl_sc_popen_e
Policies for use with fsl_sc_popen indicating how to fetch the response from invoking an external com...
@ fsl_sc_popen_e_direct
Does not work!
@ fsl_sc_popen_e_default
Mode used by fsl_sc_popen_state_empty.
@ fsl_sc_popen_e_fd
Does not work!
@ fsl_sc_popen_e_membuf
Don't use this except for experimentation.
@ fsl_sc_popen_e_filebuf
Directs the binary's stdout to a temp file bound to fsl_sc_popen_state::response::fp using fopen().
FSL_EXPORT int fsl_xfer_errorfv(fsl_xfer *xf, int code, char const *zFmt, va_list args)
va_list variant of fsl_xfer_errorf().
FSL_EXPORT int fsl_xfer_debugfv(fsl_xfer *xf, char const *zFmt, va_list args)
va_list variant of fsl_xfer_debugf().
FSL_EXPORT void fsl_xfer_debug(fsl_xfer *xf, char const *zMsg)
Equivalent to fsl_xfer_debugf(ch,"%s",zMsg) but is more efficient than that.
void(* fsl_xfer_metrics_f)(fsl_xfer_metrics const *, void *, int theRc)
A callback for use with the libfossil sync transfer subsystem.
const fsl_sc_popen_state fsl_sc_popen_state_curl
An empty state object of the type expected by fsl_sc_popen, configured to use the system's "curl" bin...
const fsl_sc fsl_sc_tracer_empty
An fsl_sc implementation which proxies another, which must be set as its state member.
FSL_EXPORT int fsl_xfer_error(fsl_xfer *xf, int code, char const *zMsg)
Equivalent to fsl_xfer_errorf(ch,code,"%s",zMsg) but more efficient.
FSL_EXPORT void fsl_xfer_config_cleanup(fsl_xfer_config *p)
Frees any memory which may be owned by p but does not free p.
FSL_EXPORT int fsl_xfer_debugf(fsl_xfer *xf, char const *zFmt,...)
If xf has a debug channel installed, the given fsl_appendf()-compatible arguments are posted to it in...
FSL_EXPORT void fsl_xfer_dbg_cleanup(fsl_xfer_dbg *p)
Frees any memory which may be owned by p but does not free p.
void fsl_xfer_metrics_f_dup(fsl_xfer_metrics const *, void *, int theRc)
A fsl_xfer_metrics_f implementation which requires that its second argument be a (fsl_xfer_metrics*).
const fsl_sc fsl_sc_popen_curl
Like fsl_sc_popen but may include different fsl_sc::flags defaults.
const fsl_sc_popen_state fsl_sc_popen_state_fth
State type for use with fsl_sc_popen_fth.
FSL_EXPORT void fsl_xfer_debug_f_buffer(fsl_xfer *xf, char const *zMsg)
An implementation for fsl_xfer::debug::callback which requires that the associated state be a (fsl_bu...
fsl_config_sync_e
Flags regarding which configuration options to sync.
@ FSL_CFG_SYNC_SUBSCRIBER
const fsl_sc_popen_state fsl_sc_popen_state_empty
An empty base fsl_sc_popen_state instance intended to be copied to intialize fsl_sc_popen_state imple...
const fsl_xfer_dbg fsl_xfer_dbg_empty
Empty-initialized instance for use in cleanly initializing objects.
FSL_EXPORT fsl_sc * fsl_sc_tracer_init(fsl_sc *chTrace, fsl_sc *ch, fsl_flag32_t traceFlags, fsl_outputer *out)
Initializes chTrace as a copy of fsl_sc_tracer_empty then directs chTrace's state to point to ch.
void fsl_xfer_metrics_f_outputer(fsl_xfer_metrics const *m, void *state, int theRc)
A fsl_xfer_metrics_f implementation which requires its second argument to be a (fsl_outputer*).
FSL_EXPORT int fsl_xfer_errorf(fsl_xfer *xf, int code, char const *zFmt,...)
Sets xf's (persistent) error state to the given information and propagates it through to xf's fsl_cx.