libfossil
sync.h File Reference

sync.h declares APIs dealing with fossil repository synchronization. More...

#include "core.h"
#include "repo.h"
Include dependency graph for sync.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  fsl_clone_config
 Options for use with fsl_clone(). More...
struct  fsl_sc
 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...
struct  fsl_sc_popen_state
 State for use with the fsl_sc_popen fsl_sc impl. More...
struct  fsl_xfer_config
 Various configuration pieces for libfossil sync transfer subsystem. More...
struct  fsl_xfer_dbg
 Internal part of fsl_sc, uplifted into its own struct to simplify proper intialization of them in downstream fsl_sc implementations. More...
struct  fsl_xfer_metrics
 Metrics for use with the library's "xfer" (sync) subsystem. More...

Macros

#define E(NAME, FLAG)
#define E(NAME, FLAG)
#define E(T, LEN)
#define fsl_clone_config_empty_m
 Empty-initialized fsl_clone_config instance intended for const-copy initialization.
#define fsl_sc_empty_m
 Empty-initialized fsl_sc instance, intended for const-copy initialization.
#define fsl_sc_popen_state_init(BinName, xInit, XCmdInit, XCleanup)
 Initializer for a fsl_sc_popen_state object which sets obj.bin.name=BinName, obj.impl.buildCommandLine=XCmdInit, and obj.impl.cleanup=XCleanup.
#define FSL_SC_READ_ALL   ((fsl_int_t)-2147483648)
 Indicates that fsl_sc::read() must transfer or copy all of its input into the result buffer.
#define FSL_SC_READ_LINE   ((fsl_int_t)-1)
 Indicates that fsl_sc::read() must read exactly 1 line of input.
#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.
#define fsl_xfcard_map(E)
#define fsl_xfcard_zeroes   0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
 A comma-separated list of zeroes: one for each entry in fsl_xfcard_e.
#define fsl_xfer_config_empty_m
 Empty-initialized fsl_xfer_config instance intended for const-copy initialization.
#define fsl_xfer_dbg_empty_m   {.callback=0, .state=0, .b=fsl_buffer_empty_m}
 Empty-initialized fsl_xfer_dbg instance for use in cleanly const-copy initializing objects.
#define fsl_xfer_metrics_empty_m
 Empty-initialized fsl_xfer_metrics instance intended for const-copy initialization.

Typedefs

typedef struct fsl_clone_config fsl_clone_config
typedef 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 synchronization.
typedef struct fsl_sc fsl_sc
typedef struct fsl_sc_popen_state fsl_sc_popen_state
typedef enum fsl_xfcard_e fsl_xfcard_e
typedef struct fsl_xfer_config fsl_xfer_config
typedef struct fsl_xfer_dbg fsl_xfer_dbg
typedef void(* fsl_xfer_dbg_f) (fsl_xfer *xf, char const *zMsg)
 Callback for xfer-layer debugging messages.
typedef struct fsl_xfer_metrics fsl_xfer_metrics
typedef void(* fsl_xfer_metrics_f) (fsl_xfer_metrics const *, void *, int theRc)
 A callback for use with the libfossil sync transfer subsystem.

Enumerations

enum  fsl_config_sync_e {
  FSL_CFG_SYNC_NONE = 0 ,
  FSL_CFG_SYNC_CSS = 1<<0 ,
  FSL_CFG_SYNC_SKIN = 1<<1 ,
  FSL_CFG_SYNC_TKT = 1<<2 ,
  FSL_CFG_SYNC_PROJ = 1<<3 ,
  FSL_CFG_SYNC_SHUN = 1<<4 ,
  FSL_CFG_SYNC_USER = 1<<5 ,
  FSL_CFG_SYNC_ADDR = 1<<6 ,
  FSL_CFG_SYNC_XFER = 1<<7 ,
  FSL_CFG_SYNC_ALIAS = 1<<8 ,
  FSL_CFG_SYNC_SUBSCRIBER = 1<<9 ,
  FSL_CFG_SYNC_IWIKI = 1<<10 ,
  FSL_CFG_SYNC_ALL = 0x0000ffff ,
  FSL_CFG_SYNC_OVERWRITE = 0x10000000
}
 Flags regarding which configuration options to sync. More...
enum  fsl_sc_F_lib_e {
  FSL_SC_F_COMPRESSED = 0x40000000 ,
  FSL_SC_F_REQUEST_HEADERS = 0x20000000 ,
  FSL_SC_F_LEAVE_TEMP_FILES = 0x10000000 ,
  FSL_SC_F_SUPPRESS_STDERR = 0x08000000 ,
  FSL_SC_F_lib_mask = 0x7FFF0000 ,
  FSL_SC_F_client_mask = ~FSL_SC_F_lib_mask
}
 Flags for use with fsl_sc::flags. More...
enum  fsl_sc_init_e {
  FSL_SC_INIT_INITIAL = 0x01 ,
  FSL_SC_INIT_REQUEST = 0x02
}
 Initialization modes for use with fsl_sc::init() implementations. More...
enum  fsl_sc_popen_e {
  fsl_sc_popen_e_filebuf = 1 ,
  fsl_sc_popen_e_membuf = 2 ,
  fsl_sc_popen_e_direct = 3 ,
  fsl_sc_popen_e_fd = 4 ,
  fsl_sc_popen_e_default = fsl_sc_popen_e_filebuf
}
 Policies for use with fsl_sc_popen indicating how to fetch the response from invoking an external command to transport fossil sync requests. More...
enum  fsl_sc_tracer_e {
  fsl_sc_tracer_map ,
  FSL_SC_TRACER_default
}
enum  fsl_xfcard_e {
  fsl_xfcard_e_unknown ,
  fsl_xfcard_map
}

Functions

int fsl_clone (fsl_clone_config const *cc, fsl_error *err)
 Under construction.
FSL_EXPORT void fsl_sc_cleanup (fsl_sc *ch)
 Calls fsl_sc_close() then, if ch->cleanup is not NULL, it is called.
FSL_EXPORT fsl_sc * fsl_sc_self (fsl_sc *ch)
 The default implementation of fsl_sc::self().
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.
FSL_EXPORT int fsl_sync_client (fsl_cx *f,...)
 NOT YET IMPLEMENTED.
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 fsl_cx * fsl_xfer_cx (fsl_xfer *xf)
 Returns xf's fsl_cx context.
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.
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.
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_buffer*).
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*) handle opened for output.
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 string form.
FSL_EXPORT int fsl_xfer_debugfv (fsl_xfer *xf, char const *zFmt, va_list args)
 va_list variant of fsl_xfer_debugf().
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 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.
FSL_EXPORT int fsl_xfer_errorfv (fsl_xfer *xf, int code, char const *zFmt, va_list args)
 va_list variant of fsl_xfer_errorf().
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*).
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*).

Variables

const fsl_clone_config fsl_clone_config_empty
 Empty-initialized fsl_clone_config instance intended for non-const-copy initialization.
const fsl_sc fsl_sc_empty
 Empty-initialized fsl_sc instance, intended for 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 fsl_sc_popen_curl
 Like fsl_sc_popen but may include different fsl_sc::flags defaults.
const fsl_sc fsl_sc_popen_fth
 Works like fsl_sc_popen_curl but uses "fossil test-http" for the transport layer.
const fsl_sc fsl_sc_popen_ssh
 Works like fsl_sc_popen_curl but uses "ssh ... fossil test-http" for the transport layer.
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" binary as the fossil sync communication channel.
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 implementations.
const fsl_sc_popen_state fsl_sc_popen_state_fth
 State type for use with fsl_sc_popen_fth.
const fsl_sc_popen_state fsl_sc_popen_state_ssh
 State type for use with fsl_sc_popen_ssh.
const fsl_sc fsl_sc_tracer_empty
 An fsl_sc implementation which proxies another, which must be set as its state member.
const fsl_xfer_config fsl_xfer_config_empty
 Empty-initialized fsl_xfer_config instance intended for non-const-copy initialization.
const fsl_xfer_dbg fsl_xfer_dbg_empty
 Empty-initialized instance for use in cleanly initializing objects.
const fsl_xfer_metrics fsl_xfer_metrics_empty
 Empty-initialized fsl_xfer_metrics instance intended for non-const copy initialization.

Detailed Description

sync.h declares APIs dealing with fossil repository synchronization.

Definition in file sync.h.

Macro Definition Documentation

◆ E [1/3]

#define E ( NAME,
FLAG )
Value:
| FSL_SC_TRACER_ ## NAME

Definition at line 1241 of file sync.h.

◆ E [2/3]

#define E ( NAME,
FLAG )
Value:
FSL_SC_TRACER_ ## NAME = FLAG,

Definition at line 1241 of file sync.h.

◆ E [3/3]

#define E ( T,
LEN )
Value:
fsl_xfcard_e_ ## T,

Definition at line 1241 of file sync.h.

◆ fsl_clone_config_empty_m

#define fsl_clone_config_empty_m
Value:
{ \
}
#define fsl_repo_create_opt_empty_m
Initialized-with-defaults fsl_repo_create_opt struct, intended for in-struct initialization.
Definition repo.h:4237
#define fsl_xfer_config_empty_m
Empty-initialized fsl_xfer_config instance intended for const-copy initialization.
Definition sync.h:1689

Empty-initialized fsl_clone_config instance intended for const-copy initialization.

Definition at line 1749 of file sync.h.

◆ fsl_sc_empty_m

#define fsl_sc_empty_m
Value:
{ \
.xfer=0, .name="unnamed", \
.flags = 0, \
.impl = {.p = 0,.type = 0}, \
.init=0, .append = 0, \
.submit=0, \
.read=0, .cleanup=0, \
.self=fsl_sc_self, \
.requestHeaders = fsl_buffer_empty_m, \
.scratch = fsl_buffer_empty_m \
}
FSL_EXPORT fsl_sc * fsl_sc_self(fsl_sc *ch)
The default implementation of fsl_sc::self().
#define fsl_url_empty_m
Initialized-with-defaults fsl_url structure, intended for const-copy initialization.
Definition util.h:6544
#define fsl_buffer_empty_m
Empty-initialized fsl_buffer instance, intended for const-copy initialization.
Definition util.h:764

Empty-initialized fsl_sc instance, intended for const-copy initialization.

Definition at line 655 of file sync.h.

◆ fsl_sc_popen_state_init

#define fsl_sc_popen_state_init ( BinName,
xInit,
XCmdInit,
XCleanup )
Value:
{ \
.impl = { \
.init=xInit, \
.buildCommandLine=XCmdInit, \
.cleanup=XCleanup, .state = 0 \
}, \
.bin = { .name = BinName, .location = 0 }, \
.process = { \
.fStdIn = 0, .fdStdOut = -1, .pid = 0 \
}, \
.request = { \
.filename = 0, .fp = 0, .count=0 \
}, \
.response = { \
.filename = 0, .fp = 0, .fd = -1, \
.count=0, .b = fsl_buffer_empty_m \
}, \
.misc = { \
.allocStamp = 0, \
.tmpfilePrefix = 0 \
}, \
}
@ fsl_sc_popen_e_default
Mode used by fsl_sc_popen_state_empty.
Definition sync.h:893

Initializer for a fsl_sc_popen_state object which sets obj.bin.name=BinName, obj.impl.buildCommandLine=XCmdInit, and obj.impl.cleanup=XCleanup.

The object is intended only for use as the fsl_sc::state pointer of a copy of fsl_sc_popen.

Definition at line 1095 of file sync.h.

◆ FSL_SC_READ_ALL

#define FSL_SC_READ_ALL   ((fsl_int_t)-2147483648)

Indicates that fsl_sc::read() must transfer or copy all of its input into the result buffer.

See FSL_SC_READ_LINE for more details.

Definition at line 219 of file sync.h.

◆ FSL_SC_READ_LINE

#define FSL_SC_READ_LINE   ((fsl_int_t)-1)

Indicates that fsl_sc::read() must read exactly 1 line of input.

Its precise value is not well-defined but it is guaranteed to be of the same type as fsl_sc::read()'s final parameter. It is not an enum entry because we cannot (in C99) portably make an enum be precisely of a specific integer type.

Definition at line 212 of file sync.h.

◆ fsl_sc_tracer_map

#define fsl_sc_tracer_map ( E)
Value:
E(none,0) \
E(init,1) E(read, 1<<1) E(append, 1<<2) \
E(cleanup, 1<<3) E(submit, 1<<4) E(self, 1<<5) \
E(debug, 1<<6)
#define E(N, V, H)
Definition core.h:497

Expands to a mapping of all fsl_sc_tracer_e types by invoking E(NAME,VALUE) for each one.

NAME is the suffix part of the name, e.g. init instead of FSL_SC_TRACER_init. VALUE is its integer value.

Definition at line 1234 of file sync.h.

◆ fsl_xfcard_map

#define fsl_xfcard_map ( E)
Value:
/* KEEP */ E(cfile,5) E(clone,5) E(clone_seqno,11) E(config,6) \
/* THESE */ E(cookie,6) E(error,5) E(file,4) E(gimme,5) E(igot,4) \
/* SORTED */ E(login,5) E(uvfile,6) E(message,7) E(pragma,6) \
/* BY */ E(private,7) E(pull,4) E(push,4) E(reqconfig,9) \
/* NAME */ E(uvgimme,7) E(uvigot,6)

Pass the name of a macro which takes 2 arguments to this macro. Macro E will be called with (NAME,LENGTH) of each sync card type. NAME is the unquoted name. LENGTH is strlen(#NAME) (which we need in a compile-time form).

!!! Keep these sorted by name and edit code which uses these to !!! match. Internals require them to be sorted by name. Actually... !!! maybe not anymore.

Definition at line 1306 of file sync.h.

◆ fsl_xfcard_zeroes

#define fsl_xfcard_zeroes   0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0

A comma-separated list of zeroes: one for each entry in fsl_xfcard_e.

Definition at line 1334 of file sync.h.

◆ fsl_xfer_config_empty_m

#define fsl_xfer_config_empty_m
Value:
{ \
.url = 0, \
.maxResponseSeconds = -1, \
.maxResponseBytes = 2500000, \
.verbosity = 0, \
.compressTraffic=false, \
.listener = fsl_msg_listener_empty_m, \
.trace = { \
.mask = 0, \
.outputer = fsl_outputer_FILE_m \
}, \
.op = { \
.clone = 0, \
.push = false, \
.pull = false, \
.privateContent = false, \
.autosync = false \
}, \
.metrics = { \
.callback = NULL, .state = NULL \
}, \
.password = { \
.callback = NULL, \
.state = NULL, \
.save = false \
} \
}
#define fsl_msg_listener_empty_m
Definition core.h:810
#define fsl_xfer_dbg_empty_m
Empty-initialized fsl_xfer_dbg instance for use in cleanly const-copy initializing objects.
Definition sync.h:102
#define fsl_outputer_FILE_m
fsl_outputer initializer which uses fsl_flush_f_FILE() and fsl_output_f_FILE().
Definition util.h:375

Empty-initialized fsl_xfer_config instance intended for const-copy initialization.

Definition at line 1689 of file sync.h.

◆ fsl_xfer_dbg_empty_m

#define fsl_xfer_dbg_empty_m   {.callback=0, .state=0, .b=fsl_buffer_empty_m}

Empty-initialized fsl_xfer_dbg instance for use in cleanly const-copy initializing objects.

Definition at line 102 of file sync.h.

◆ fsl_xfer_metrics_empty_m

#define fsl_xfer_metrics_empty_m
Value:
{ \
.trips = 0, \
.iGotSent = 0, \
.privIGot = 0, \
.gimmeSent = 0, \
.fileSent = 0, \
.deltaSent = 0, \
.fileRcvd = 0, \
.deltaRcvd = 0, \
.danglingFile = 0, \
.rcvdArtifacts = 0, \
.rcvdCards = 0, \
.sentCards = 0, \
.largestCardPayload = 0, \
.largestDecompressedResponse = 0, \
.bytesReadCompressed = 0, \
.bytesReadUncompressed = 0, \
.bytesWritten = 0, \
.cardsRx = {fsl_xfcard_zeroes}, \
.cardsTx = {fsl_xfcard_zeroes}, \
.timer = { \
.read = fsl_timer_empty_m, \
.submit = fsl_timer_empty_m, \
.uncompress = fsl_timer_empty_m, \
.process = fsl_timer_empty_m \
} \
}
#define fsl_xfcard_zeroes
A comma-separated list of zeroes: one for each entry in fsl_xfcard_e.
Definition sync.h:1334
#define fsl_timer_empty_m
Initialized-with-defaults fsl_timer instance, intended for const copy initialization.
Definition util.h:5471

Empty-initialized fsl_xfer_metrics instance intended for const-copy initialization.

Definition at line 1418 of file sync.h.

Typedef Documentation

◆ fsl_clone_config

typedef struct fsl_clone_config fsl_clone_config

Definition at line 1743 of file sync.h.

◆ fsl_pw_f

typedef 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 synchronization.

Its first two arguments are current fsl_cx and the URL the password is being requested for. The final argument is implementation-dependent state.

Implementations must somehow collect a password for the given URL, append a copy of it to bPout, and return 0 on success. On error they must return non-0, preferably the result of passing f to fsl_cx_err_set(). If appending the result to the buffer fails, it's caused (barring invalid arguments) by an OOM, in which case that code can be returned directly.

It is legal for implementations to use bOut for construct their input prompt, so long as they pass it to fsl_buffer_reuse() before appending the password to it.

To indicate a non-error when no password is available, return 0 and do not modify bOut (or pass it to fsl_buffer_reuse() before returning). In such cases the library will continue as if no credentials are available, which might trigger an error later on if credentials are required.

bOut is owned by the library. The state argument is owned by whoever put it there.

Design notes:

Sync passwords are stored, if at all, in f's global config database. Each has a key of "libfossil-sync-pw:" + the URL shorn of any password part. Thus saving a password for "http://foo:bar@baz/bar" will leave a config entry named "libfossil-sync-pw:http://foo@baz/bar". The passwords are stored as conventionally-fossil-hashed passwords.

Passwords are specific to a given repository "project-code", so attempting to sync to the same URL for multiple project codes will leave the sync unable to log in to any but the most recent one for which the password was saved.

This password storage is different from fossil(1)'s. The thinking is "separate apps, separate passwords", though the passwords all go in the same database. That's subject to change, though.

Definition at line 1522 of file sync.h.

◆ fsl_sc

typedef struct fsl_sc fsl_sc

Definition at line 28 of file sync.h.

◆ fsl_sc_popen_state

typedef struct fsl_sc_popen_state fsl_sc_popen_state

Definition at line 896 of file sync.h.

◆ fsl_xfcard_e

typedef enum fsl_xfcard_e fsl_xfcard_e

Definition at line 1329 of file sync.h.

◆ fsl_xfer_config

typedef struct fsl_xfer_config fsl_xfer_config

Definition at line 1683 of file sync.h.

◆ fsl_xfer_dbg

typedef struct fsl_xfer_dbg fsl_xfer_dbg

Definition at line 98 of file sync.h.

◆ fsl_xfer_dbg_f

typedef void(* fsl_xfer_dbg_f) (fsl_xfer *xf, char const *zMsg)

Callback for xfer-layer debugging messages.

TODO consolidate this with the fsl_msg system.

Definition at line 34 of file sync.h.

◆ fsl_xfer_metrics

typedef struct fsl_xfer_metrics fsl_xfer_metrics

Definition at line 1412 of file sync.h.

◆ fsl_xfer_metrics_f

typedef void(* fsl_xfer_metrics_f) (fsl_xfer_metrics const *, void *, int theRc)

A callback for use with the libfossil sync transfer subsystem.

Implementations are passed the sync-related metrics, their state object, and the result code of the sync (so that they can choose whether or not to skip any display on error).

Definition at line 1458 of file sync.h.

Enumeration Type Documentation

◆ fsl_config_sync_e

Flags regarding which configuration options to sync.

This should probably be strings so that we don't have to adapt this for every protocol addition.

Enumerator
FSL_CFG_SYNC_NONE 
FSL_CFG_SYNC_CSS 
FSL_CFG_SYNC_SKIN 
FSL_CFG_SYNC_TKT 
FSL_CFG_SYNC_PROJ 
FSL_CFG_SYNC_SHUN 
FSL_CFG_SYNC_USER 
FSL_CFG_SYNC_ADDR 
FSL_CFG_SYNC_XFER 
FSL_CFG_SYNC_ALIAS 
FSL_CFG_SYNC_SUBSCRIBER 
FSL_CFG_SYNC_IWIKI 
FSL_CFG_SYNC_ALL 
FSL_CFG_SYNC_OVERWRITE 

Definition at line 706 of file sync.h.

◆ fsl_sc_F_lib_e

Flags for use with fsl_sc::flags.

The top-most 8 bits are reserved for use by common library-level flags which a fsl_sc implementation may choose to support or may be required to support.

Enumerator
FSL_SC_F_COMPRESSED 

Tells the fsl_sc impl that it should post data using the HTTP Content-Type value of "application/x-fossil" instead of "application/x-fossil-uncompressed".

The former will have a fossil-compressed response payload[^1] whereas the latter will have an uncompressed response. Compressed payloads require far more memory to process but can save considerable network bandwidth.

fsl_sc implementations are required to honor this flag, in that they must set the appropriate Content-Type request header, so that the library can Do The Right Thing without requiring that each fsl_sc implementation know to stream or buffer the compressed content.

This is a hint for the remote, but the remote may override that, sending uncompressed responses instead of compressed. The remote will never do the opposite, convering a request for an uncompressed response to a compressed one.

Compression may be handled differently for certain sync response types. e.g., a protocol-version-3 clone request will not emit a fully-compressed response because most of the response body is already compressed in that case. The fsl_sc implementations need not concern themselves with that, however.

Similarly, then fossil is operated via its "test-http" facility, it does not compress responses.

When this flag is set, the sync process will read all of the response content from the fsl_sc instance and then take over reading of the response from there so that fsl_sc implementations do not have to deal with those details.

Because compression support is so memory-hungry, it is opt-in flag instead of an opt-out. Compression will save network bandwidth but costs the client application and the remote fossil instance boatloads of RAM.

[^1]: zlib compress() with a 4-byte big-endian header encoding the decompressed size.

FSL_SC_F_REQUEST_HEADERS 

For impls with this flag set, the library will populate their fsl_sc::requestHeaders immediately before calling the impl's submit() method.

Some impls generate their own headers or feed them into a proxy application in a different way, so don't need this. e.g. the curl-binary-based impl passes headers to curl in the form of CLI flags.

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 examined for testing and debugging.

Implementations are recommended to send a fsl_xfer_emit_msg() message with the type FSL_MSG_TMPFILE and the name of the file in the message at the time when they would have otherwise been deleted, to facilitate matching temp files to their purpose.

FSL_SC_F_SUPPRESS_STDERR 

Impls which might, due to shelling out, emit info to stderr are expected to honor this flag and redirect stderr to /dev/null (or equivalent) if at all possible.

FSL_SC_F_lib_mask 

The mask of FSL_SC_F_... bits which are reserved for use by library-level options.

FSL_SC_F_client_mask 

The mask of FSL_SC_F_... bits which are reserved for use by client-level options.

Definition at line 119 of file sync.h.

◆ fsl_sc_init_e

Initialization modes for use with fsl_sc::init() implementations.

Enumerator
FSL_SC_INIT_INITIAL 

Indicates that the fsl_sc instance should initialize any core resources but not any request/response resources.

See fsl_sc::init() for more details.

FSL_SC_INIT_REQUEST 

Indicates that the object must (re)initialize any state needed for constructing a request.

e.g. initializing a buffer or temp file. The xfer layer may use this to compose a follow-up response while it is still reading a remote's response.

See fsl_sc::init() for more details.

Design note: there is no FSL_SC_INIT_RESPONSE counterpart because that role is effectively filled by fsl_sc::submit(), which initiates the processing of any response.

Definition at line 224 of file sync.h.

◆ fsl_sc_popen_e

Policies for use with fsl_sc_popen indicating how to fetch the response from invoking an external command to transport fossil sync requests.

This is all internal experimentation, not part of the public API.

Enumerator
fsl_sc_popen_e_filebuf 

Directs the binary's stdout to a temp file bound to fsl_sc_popen_state::response::fp using fopen().

This "should" work the same as fsl_sc_popen_e_direct but this one works where that one doesn't, for reasons unknown.

Measurements show, somewhat surprisingly, this to be significantly faster than fsl_sc_popen_e_membuf (anywhere from 30% to twice as fast, depending on the test run), as well as far memory-lighter: 410kb peak RAM vs 9.4MB peak ram for the same clone of fossil's canonical repository.

fsl_sc_popen_e_membuf 

Don't use this except for experimentation.

Slurp whole response into a fsl_buffer at fsl_sc_popen_state::response. This works but can use a huge amount of memory.

This is slower than fsl_sc_popen_e_filebuf and much more memory-hungry. The main speed culprit seems to be fsl_buffer_stream_lines(), which takes up some 25% of the test run's CPU instructions (as reported by callgrind).

fsl_sc_popen_e_direct 

Does not work!

Don't buffer: read response from the binary's stdout, bound to fsl_sc_popen_state::process::fdStdOut.

This mode is currently failing with curious read failures: for some cards, reading the payload leaves (apparently) pieces which are then read by the next read-line op and of course don't parse as a card. The cause is as-yet unknown but it's got to be a bug somewhere in this code.

fsl_sc_popen_e_fd 

Does not work!

Read the binary's stdout using an unbuffered file descriptor open()ed on fsl_sc_popen_state::response::fd.

This is is known to fail with "not found" for the output file after fsl_popen2()'ing the command (at which point we expect the output to be there). This "should" fail in the same way as fsl_sc_popen_e_direct, as we're doing the same thing just with another file of indirection.

fsl_sc_popen_e_default 

Mode used by fsl_sc_popen_state_empty.

Definition at line 831 of file sync.h.

◆ fsl_sc_tracer_e

Enumerator
fsl_sc_tracer_map 
FSL_SC_TRACER_default 

Definition at line 1240 of file sync.h.

◆ fsl_xfcard_e

Ids for fossil sync protocol card types.

Enumerator
fsl_xfcard_e_unknown 
fsl_xfcard_map 

Definition at line 1317 of file sync.h.

Function Documentation

◆ fsl_clone()

int fsl_clone ( fsl_clone_config const * cc,
fsl_error * err )

Under construction.

◆ fsl_sc_cleanup()

FSL_EXPORT void fsl_sc_cleanup ( fsl_sc * ch)

Calls fsl_sc_close() then, if ch->cleanup is not NULL, it is called.

Then it frees all of ch's buffers. Does not free ch.

This is prefered to calling ch->cleanup() directly because this ensures that ch's buffers are accounted for.

References FSL_EXPORT.

◆ fsl_sc_self()

FSL_EXPORT fsl_sc * fsl_sc_self ( fsl_sc * ch)

The default implementation of fsl_sc::self().

Simply returns ch.

References FSL_EXPORT.

◆ fsl_sc_tracer_init()

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.

Returns chTrace on success. On error it returns NULL.

References FSL_EXPORT.

◆ fsl_sync_client()

FSL_EXPORT int fsl_sync_client ( fsl_cx * f,
... )

NOT YET IMPLEMENTED.

This interface is experimental and subject to change. The plan, however, is...

Fluid. The plan is fluid.

On success, returns 0, else it returns one of any number of fsl_rc_e codes and may be propagating error information accessible via fsl_cx_err_get().

References FSL_EXPORT.

◆ fsl_xfer_config_cleanup()

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.

References FSL_EXPORT.

◆ fsl_xfer_cx()

FSL_EXPORT fsl_cx * fsl_xfer_cx ( fsl_xfer * xf)

Returns xf's fsl_cx context.

This is used in fsl_sc callback implementations.

References FSL_EXPORT.

◆ fsl_xfer_dbg_cleanup()

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.

References FSL_EXPORT.

◆ fsl_xfer_debug()

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.

References FSL_EXPORT.

◆ fsl_xfer_debug_f_buffer()

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_buffer*).

On each call zMsg is appended as-is to that buffer, without additional decoration.

References FSL_EXPORT.

◆ fsl_xfer_debug_f_FILE()

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*) handle opened for output.

Each call sends zMsg to that FILE handle via fprintf(), without additional decoration.

References FSL_EXPORT.

◆ fsl_xfer_debugf()

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 string form.

The output may be prefixed with other information.

If xf has no debugging channel then this function has no side-effects.

This function adds a newline to the result if it does not end in one.

Returns 0 on success and the only error case is a formatting buffer allocation error, which causes FSL_RC_OOM to be returned. Such results should not be propagated by client code - an OOM is innocuous in the context of debugging output.

This function requires allocating memory, and re-uses a buffer dedicated to that purpose. In ideal cases, it won't have to allocate more than once during the lifetime of a given fsl_xf instance.

WARNING: fsl_xfer_config::debug-bound logging functions must not call this, else there will be an endless loop and eventual stack overflow.

References FSL_EXPORT.

◆ fsl_xfer_debugfv()

FSL_EXPORT int fsl_xfer_debugfv ( fsl_xfer * xf,
char const * zFmt,
va_list args )

va_list variant of fsl_xfer_debugf().

References FSL_EXPORT.

◆ fsl_xfer_error()

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.

References FSL_EXPORT.

◆ fsl_xfer_errorf()

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.

After this, further calls to fsl_xf-taking APIs will fail.

This is intended to only be used from fsl_sc implementations and this library's own internals.

This function prefixes the message with some form of ch->name and the fsl_rc_cstr() value of the given result code.

Returns the given code, or FSL_RC_ERROR if code is 0. i.e. it never returns 0. A code value of 0 is semantically illegal in this context.

References FSL_EXPORT.

◆ fsl_xfer_errorfv()

FSL_EXPORT int fsl_xfer_errorfv ( fsl_xfer * xf,
int code,
char const * zFmt,
va_list args )

va_list variant of fsl_xfer_errorf().

References FSL_EXPORT.

◆ fsl_xfer_metrics_f_dup()

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*).

It copies the first argument bitwise over the second. The final argument is ignored.

◆ fsl_xfer_metrics_f_outputer()

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*).

It sends all output to that channel. If theRc is non-0 then this is a no-op.

Variable Documentation

◆ fsl_clone_config_empty

const fsl_clone_config fsl_clone_config_empty
extern

Empty-initialized fsl_clone_config instance intended for non-const-copy initialization.

◆ fsl_sc_empty

const fsl_sc fsl_sc_empty
extern

Empty-initialized fsl_sc instance, intended for copy initialization.

◆ fsl_sc_popen

const fsl_sc fsl_sc_popen
extern

An empty base fsl_sc instance for use with fsl_sc_popen_state implementations.

To use it:

  1. Bitwise-copy it over a fsl_sc instance.
  2. Set its state.p member to point to a valid fsl_sc_popen_state instance.
  3. Do not modify its state.type member.

Nuances of this implementation:

  • Its state.p must be a (fsl_sc_popen_state*) and state.type must be &fsl_sc_popen. This initializer does that latter part.
  • If state->flag.allocStamp is not 0, it must point to state->p. This indicates that this object owns its state pointer and will free it via this object's cleanup() method.

◆ fsl_sc_popen_curl

const fsl_sc fsl_sc_popen_curl
extern

Like fsl_sc_popen but may include different fsl_sc::flags defaults.

The state.p member must point to a fsl_sc_popen_state instance initialized by bitwise copying from fsl_sc_popen_state_curl.

Example usage:

st.state.p = &pst;
State for use with the fsl_sc_popen fsl_sc impl.
Definition sync.h:907
The fsl_sc class encapsulates a streamable (as opposed to random-access) I/O channel intended solely ...
Definition sync.h:312
void * p
Arbitrary state for implementations.
Definition sync.h:357
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_popen_curl
Like fsl_sc_popen but may include different fsl_sc::flags defaults.

◆ fsl_sc_popen_fth

const fsl_sc fsl_sc_popen_fth
extern

Works like fsl_sc_popen_curl but uses "fossil test-http" for the transport layer.

The fsl_sc::state::p pointer of these objects MUST be a pointer to an fsl_sc_popen_state object which was initialized by copying it from fsl_sc_popen_state_fth. Example:

sc.state.p = &sc;
const fsl_sc fsl_sc_popen_fth
Works like fsl_sc_popen_curl but uses "fossil test-http" for the transport layer.
const fsl_sc_popen_state fsl_sc_popen_state_fth
State type for use with fsl_sc_popen_fth.

◆ fsl_sc_popen_ssh

const fsl_sc fsl_sc_popen_ssh
extern

Works like fsl_sc_popen_curl but uses "ssh ... fossil test-http" for the transport layer.

The fsl_sc::state::p pointer of these objects MUST be a pointer to an fsl_sc_popen_state object which was initialized by copying it from fsl_sc_popen_state_ssh. Example:

sc.state.p = &sc;
const fsl_sc fsl_sc_popen_ssh
Works like fsl_sc_popen_curl but uses "ssh ... fossil test-http" for the transport layer.
const fsl_sc_popen_state fsl_sc_popen_state_ssh
State type for use with fsl_sc_popen_ssh.

By default it assumes that fossil(1) is in the remote's $PATH, but it can be explicitly told the path by providing a query argument to the URL: fossil=/path/to/remote/fossil (URL-encoded if it contains anything which needs to be).

Peculiarities of this implementation:

  • Any password part of the URL is used as the remote fossil password, not the SSH password. The URL part is stripped before passing the URL on to ssh. However, fossil does not honor logins over ssh (the user is given full admin access), so applying the fossil login card here is a matter of conscience and library-level consistency, not one of necessity.

◆ fsl_sc_popen_state_curl

const fsl_sc_popen_state fsl_sc_popen_state_curl
extern

An empty state object of the type expected by fsl_sc_popen, configured to use the system's "curl" binary as the fossil sync communication channel.

◆ fsl_sc_popen_state_empty

const fsl_sc_popen_state fsl_sc_popen_state_empty
extern

An empty base fsl_sc_popen_state instance intended to be copied to intialize fsl_sc_popen_state implementations.

Implementations must set the bin.name and impl.buildCommandLine members to whatever is appropriate for the object's external binary.

◆ fsl_sc_popen_state_fth

const fsl_sc_popen_state fsl_sc_popen_state_fth
extern

State type for use with fsl_sc_popen_fth.

◆ fsl_sc_popen_state_ssh

const fsl_sc_popen_state fsl_sc_popen_state_ssh
extern

State type for use with fsl_sc_popen_ssh.

◆ fsl_sc_tracer_empty

const fsl_sc fsl_sc_tracer_empty
extern

An fsl_sc implementation which proxies another, which must be set as its state member.

This proxy calls fsl_sc_debug() with the name of each called fsl_sc method before passing the method on to the proxied changed.

The exception is: the fsl_sc::debug.callback method is passed that through directly because calling fsl_sc_debug() on itself leads to an endless loop.

Example:

fsl_sc orig = ...some other sc...;
fsl_sc_tracer_init(&tracer, &orig);
const fsl_sc fsl_sc_tracer_empty
An fsl_sc implementation which proxies another, which must be set as its state member.
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.

Then use tracer in place of orig with the downstream APIs. Calling tracer.cleanup(&tracer) will also cleanup orig.

To customize where the debug messages go, replace the object's debug.callback method with one which expects an object of this type and emit them from there wherever you like. Just don't call any of the fsl_sc_debug() family of functions on that object, else an endless debig call loop will trigger.

◆ fsl_xfer_config_empty

const fsl_xfer_config fsl_xfer_config_empty
extern

Empty-initialized fsl_xfer_config instance intended for non-const-copy initialization.

◆ fsl_xfer_dbg_empty

const fsl_xfer_dbg fsl_xfer_dbg_empty
extern

Empty-initialized instance for use in cleanly initializing objects.

◆ fsl_xfer_metrics_empty

const fsl_xfer_metrics fsl_xfer_metrics_empty
extern

Empty-initialized fsl_xfer_metrics instance intended for non-const copy initialization.