libfossil
sync.h
Go to the documentation of this file.
1/* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2/* vim: set ts=2 et sw=2 tw=80: */
3#if !defined(ORG_FOSSIL_SCM_FSL_SYNC_H_INCLUDED)
4#define ORG_FOSSIL_SCM_FSL_SYNC_H_INCLUDED
5/*
6 Copyright 2025 The Libfossil Authors, see LICENSES/BSD-2-Clause.txt
7
8 SPDX-License-Identifier: BSD-2-Clause-FreeBSD
9 SPDX-FileCopyrightText: 2025 The Libfossil Authors
10 SPDX-FileType: Code
11
12 Heavily indebted to the Fossil SCM project (https://fossil-scm.org).
13*/
14
15/** @file sync.h
16
17 sync.h declares APIs dealing with fossil repository
18 synchronization.
19*/
20
21#include "core.h" /* MUST come first b/c of config macros */
22#include "repo.h"
23
24#if defined(__cplusplus)
25extern "C" {
26#endif
27
28typedef struct fsl_sc fsl_sc;
29
30/**
31 Callback for xfer-layer debugging messages. TODO consolidate this
32 with the fsl_msg system.
33 */
34typedef void (*fsl_xfer_dbg_f)(fsl_xfer *xf, char const * zMsg);
35
36/**
37 Internal part of fsl_sc, uplifted into its own struct to simplify
38 proper intialization of them in downstream fsl_sc implementations.
39*/
41 /**
42 This optional method is intended to be set by client-level code,
43 not the sync channel implementor.
44
45 If not NULL, the library or fsl_sc implementations may emit
46 debugging output via this function.
47
48 For output channel legibility, zMsg should always end with a
49 newline (fsl_xfer_debug() and friends will automatically add one if
50 needed).
51
52 Implementations are free to mangle or emit the message in any
53 form they like.
54
55 Design note: its return type is void, but experience with binding
56 C to Java and C++ shows that such bindings may need to propagate
57 unexpected exceptions (e.g. resource acquisition failure, logging
58 failure, etc.) somehow through the C API, and the conventional
59 generic way to do that is to have a result code. In normal use,
60 it is never expected that a debugging function fails in a way
61 which impacts the non-debugging functionality, but if an
62 implementation absolutely must report an error, they should call
63 fsl_xfer_error(), and that will be propagated back from this
64 call. Channels, however, are _not_ required to check that after
65 every debug call - they may assume success when the debug
66 function is called, as the debug channel should not interfere
67 with the sync channel's operation.
68
69 @see fsl_xfer_debug_f_FILE()
70 @see fsl_xfer_debug_f_buffer()
71 */
73
74 /**
75 Available in callback() implementations via ch->debug.state.
76
77 This memory is not owned by this object. It's owned by whoever
78 set this member to non-NULL.
79 */
80 void * state;
81
82 /**
83 This is a scratch buffer solely for internal use by:
84
85 1) library APIs like fsl_xfer_debugf()
86
87 2) fsl_sc method implementations which do not themselves call
88 into (1) while using this buffer.
89
90 Without this, fsl_xfer_debug() becomes unduly memory-costly. This
91 memory is owned by the library and gets cleared by
92 fsl_sc_cleanup(). fsl_sc::cleanup() implementations may clean it
93 up but are not required to.
94 */
96};
97
99
100/** Empty-initialized fsl_xfer_dbg instance for use in cleanly
101 const-copy initializing objects. */
102#define fsl_xfer_dbg_empty_m {.callback=0, .state=0, .b=fsl_buffer_empty_m}
103
104/** Empty-initialized instance for use in cleanly initializing
105 objects. */
107
108/**
109 Frees any memory which may be owned by p but does not
110 free p.
111*/
113
114/**
115 Flags for use with fsl_sc::flags. The top-most 8 bits are reserved
116 for use by common library-level flags which a fsl_sc implementation
117 may choose to support or may be required to support.
118*/
120 /**
121 Tells the fsl_sc impl that it should post data using the HTTP
122 Content-Type value of "application/x-fossil" instead of
123 "application/x-fossil-uncompressed". The former will have a
124 fossil-compressed response payload[^1] whereas the latter will
125 have an uncompressed response. Compressed payloads require far
126 more memory to process but can save considerable network
127 bandwidth.
128
129 fsl_sc implementations are required to honor this flag, in that
130 they must set the appropriate Content-Type request header, so
131 that the library can Do The Right Thing without requiring that
132 each fsl_sc implementation know to stream or buffer the
133 compressed content.
134
135 This is a _hint_ for the remote, but the remote may override
136 that, sending uncompressed responses instead of compressed.
137 The remote will never do the opposite, convering a request for
138 an uncompressed response to a compressed one.
139
140 Compression may be handled differently for certain sync response
141 types. e.g., a protocol-version-3 clone request will _not_ emit a
142 fully-compressed response because most of the response body is
143 already compressed in that case. The fsl_sc implementations need
144 not concern themselves with that, however.
145
146 Similarly, then fossil is operated via its "test-http" facility,
147 it does not compress responses.
148
149 When this flag is set, the sync process will read all of the
150 response content from the fsl_sc instance and then take over
151 reading of the response from there so that fsl_sc implementations
152 do not have to deal with those details.
153
154 Because compression support is so memory-hungry, it is opt-in
155 flag instead of an opt-out. Compression will save network
156 bandwidth but costs the client application and the remote fossil
157 instance boatloads of RAM.
158
159 [^1]: zlib compress() with a 4-byte big-endian header encoding
160 the decompressed size.
161 */
163
164 /**
165 For impls with this flag set, the library will populate their
166 fsl_sc::requestHeaders immediately before calling the impl's
167 submit() method. Some impls generate their own headers or feed
168 them into a proxy application in a different way, so don't need
169 this. e.g. the curl-binary-based impl passes headers to curl
170 in the form of CLI flags.
171 */
173
174 /**
175 Impls which use temp files must honor this flag by _not_ deleting
176 those files, so that they can be examined for testing and
177 debugging.
178
179 Implementations are recommended to send a fsl_xfer_emit_msg()
180 message with the type FSL_MSG_TMPFILE and the name of the
181 file in the message at the time when they would have otherwise
182 been deleted, to facilitate matching temp files to their purpose.
183 */
185
186 /**
187 Impls which might, due to shelling out, emit info to stderr are
188 expected to honor this flag and redirect stderr to /dev/null (or
189 equivalent) if at all possible.
190 */
192
193 /**
194 The mask of FSL_SC_F_... bits which are reserved for use by
195 library-level options.
196 */
197 FSL_SC_F_lib_mask = 0x7FFF0000,
198 /**
199 The mask of FSL_SC_F_... bits which are reserved for use by
200 client-level options.
201 */
203};
204
205/**
206 Indicates that fsl_sc::read() must read exactly 1 line of
207 input. Its precise value is not well-defined but it is guaranteed
208 to be of the same type as fsl_sc::read()'s final parameter. It is
209 not an enum entry because we cannot (in C99) portably make an enum
210 be precisely of a specific integer type.
211*/
212#define FSL_SC_READ_LINE ((fsl_int_t)-1)
213
214/**
215 Indicates that fsl_sc::read() must transfer or copy all of its
216 input into the result buffer. See FSL_SC_READ_LINE for more
217 details.
218*/
219#define FSL_SC_READ_ALL ((fsl_int_t)-2147483648)
220
221/**
222 Initialization modes for use with fsl_sc::init() implementations.
223*/
225 /**
226 Indicates that the fsl_sc instance should initialize any core
227 resources but not any request/response resources.
228
229 See fsl_sc::init() for more details.
230 */
232
233 /**
234 Indicates that the object must (re)initialize any state needed
235 for constructing a request. e.g. initializing a buffer or temp
236 file. The xfer layer may use this to compose a follow-up response
237 while it is still reading a remote's response.
238
239 See fsl_sc::init() for more details.
240
241 Design note: there is no FSL_SC_INIT_RESPONSE counterpart because
242 that role is effectively filled by fsl_sc::submit(), which
243 initiates the processing of any response.
244 */
246};
247
248/**
249 The fsl_sc class encapsulates a streamable (as opposed to
250 random-access) I/O channel intended solely for use in implementing
251 fossil(1)'s sync protocol in libfossil in an I/O-channel-agnostic
252 manner. (Thus the name "sc" - an abbreviation of "sync channel".)
253 The idea is that we can hook up arbitrary streamable I/O channels
254 via this interface, e.g. HTTP-, SSH-, and file-driven channels.
255
256 Each instance must be fully populated to set up its fsl_cx, I/O
257 methods, and non-NULL values for all requires methods (init(),
258 cleanup(), etc.). Each instance may have arbitrary state associated
259 with it, but whether such state must be provided by the user, or is
260 created/initialized by the open() implementation, is
261 implementation-defined.
262
263 A channel's lifecycle, in terms of its API, goes something like:
264
265 - User populates a state object of the
266 type required by the channel.
267
268 - User cleanly initializes a fsl_sc instance by copy-initializing
269 it from a known-good starting point, e.g. fsl_sc_empty or
270 fsl_sc_popen. We'll call this object "sc".
271
272 - User sets sc.state.p if necessary for the implementation.
273 e.g. fsl_sc_popen requires that its state pointer refer to a
274 properly-populated fsl_sc_popen_state object, e.g. a copy of
275 fsl_sc_popen_state_curl.
276
277 - User passes it off to the library for handling. That API is still
278 TBD.
279
280 - Its init() method is called.
281
282 - Its append() method will be called an arbitrary number of times
283 to populate it with a fossil sync request payload.
284
285 - Its submit() method is called to finalize the request payload
286 and send it wherever it needs to go.
287
288 - Its read() method is used to read the response payload. Sync
289 protocol "cards" are read line-by-line and card-level payloads
290 are read in their-payload-sized chunks.
291
292 - For a multi-round-trip sync, its init() method may be called once
293 per round trip, starting the process over.
294
295 - Its cleanup() method is called to clean it up.
296
297
298 Open design issues:
299
300 - For some channels, the model does not support that posted content
301 can be passed through without an extra copy, as we can't generate
302 the channel-specific headers until we have the content, and need
303 a second buffer to concatenate the headers and content.
304 Accounting for HTTP's Content-Size header and the sync login card
305 (also sent via HTTP header) are the main culprits here.
306
307 - The status message interface may not be sufficient. We need to
308 empower apps to do things like display progress dialogs, even if
309 they're not as granular as real-time counts of network traffic
310 and related channel-specific state.
311*/
312struct fsl_sc {
313 /**
314 The "transfer context" for this channel. This is set by the
315 library and is needed for calling functions like fsl_xfer_emit()
316 from within fsl_sc member function code.
317 */
319
320 /**
321 A debugging-purposes name for this channel,
322 e.g. "http-socket". The bytes are considered to be static, and
323 must outlive any instance of this class which uses them.
324 */
325 char const * name;
326
327 /**
328 The remote fossil URL.
329
330 It is up to the client to either set up the URL before passing
331 this object on to the library or to ensure that the last-sync-url
332 is of a schema compatible with this instance.
333
334 It is also up to the client to ensure that the URL scheme matches
335 the fsl_sc implementation. How best to do that is still TBD.
336
337 This memory is owned by this object.
338 */
340
341 /**
342 Flags for customizing certain behaviors.
343 */
345
346 /**
347 Implementation-dependent state.
348 */
349 struct {
350 /**
351 Arbitrary state for implementations. Its ownership is
352 implementation-defined, as is whether this object's init()
353 method will populate this or whether the client must provide
354 it. If this object owns it, its cleanup() method must free the
355 memory and clear this member.
356 */
357 void * p;
358 /**
359 An optional value which uniquely identifies with a specific
360 type. Intended as a semi-type-safety measure for this->state.p.
361 i.e. don't assume p is of the desired type unless this matches
362 some well-defined value (which need not be public).
363 */
364 void const * type;
366
367 /**
368 This callback's responsibility is to initialize and validate any
369 resources which may be implied via this->impl.
370
371 The second argument tells the implementation what type of
372 initialization is required, as per the fsl_sc_init_e docs.
373
374 FSL_SC_INIT_INITIAL is only ever passed one time per object and
375 is guaranteed to be called before FSL_SC_INIT_REQUEST is. If the
376 channel needs to perform any validation, that is the time to do
377 is.
378
379 FSL_SC_INIT_REQUEST is called each time a new request body needs
380 to be generated. Implementations must discard any prior
381 request-specific state when initialized with this value.
382
383 ch->flags must be set before calling this and must not be
384 modified afterwards. The library will set the ch->xfer member.
385
386 It is up to the direct users of this API to ensure that their
387 fsl_sc instances contain no randomly-initialized state before the
388 initial call to this function.
389
390 This call may, depending on the impl, initialize ch->impl,
391 whereas some channel implementations may require that the caller
392 populate ch->impl with an implementation-defined "something".
393 Those details are to be documented for each concrete
394 implementation.
395
396 Implementations must return 0 on success. On error they must
397 return a fsl_rc_e value and should ideally use fsl_xfer_error()
398 on ch->xfer to report an error message.
399
400 The library guarantees that a db transaction will be in effect
401 when it calls this function, and that failure from any fsl_sc API
402 will be propagated back and cause the transaction to roll back.
403
404 Regardless of success or failure, clients are required to
405 eventually call the cleanup() method if they call init(). On a
406 failed init() call, it is not generically knowable whether it's
407 okay to call init() again, and clients should not do so.
408
409 Whether or not this step will initialize any network and/or FILE
410 and/or RPC connections is left to the implementation. It may do
411 so here, if needed, or it may delay such things until submit().
412 */
413 int (*init)(fsl_sc *ch, enum fsl_sc_init_e mode);
414
415 /**
416 Must append the first n bytes of pIn to the outbound sync request
417 payload. The library will call this an arbitrary number of times
418 to generate the sync body payload.
419
420 Implementations are free to buffer, or not, the payload,
421 depending on their requirements, but practical considerations may
422 make buffering unavoidable. e.g. an HTTP implementation will
423 require the full payload before sending, so that the Content-Size
424 header can be set and the headers pushed before the payload is. A
425 streaming-to-(FILE*) implementation, however, has no such
426 requirements, so could avoid an extra buffering step (unless,
427 perhaps, that file's contents are intended for further processing
428 by, e.g., netcat(1), in which case HTTP headers would need to be
429 prepended).
430
431 Achtung: calling this API directly from client code will
432 effectively corrupt the output. The library internals funnel all
433 fsl_sc output traffic through a single point so that the size of
434 the request and its SHA1 hash can be kept track of (both are
435 needed for sending authenticated requests). Calling this API
436 directly will bypass that and result in request bodies whose
437 hashes do not match fossil's authentication expectations.
438 */
439 int (*append)(fsl_sc *ch, void const * pIn, fsl_size_t n);
440
441 /**
442 Tells the channel that the library is done building the request
443 payload and it should be submitted.
444
445 If this method buffers its response, it may close (if still
446 opened) any channel opened by init() but should retain any state
447 which might be needed for reestablishing that connection. If it
448 does not buffer the response, it may keep the channel open for
449 downstream read() calls.
450
451 This is never called before init() is passed FSL_SC_INIT_REQUEST
452 and is never called when any call to init() fails.
453
454 If loginCard is not NULL, it contains the full content of a login
455 card for the request. Implementations must emit these bytes
456 as an HTTP header in this form:
457
458 ```
459 Cookie: x-f-l-c=UrlEncodedValueOfTheCard
460 ```
461
462 Which, in C, might look something like:
463
464 ```
465 char * z = fsl_mprtinf("Cookie: x-f-l-c=%t\r\n",
466 fsl_buffer_cstr(loginCard));
467 fsl_free(z);
468 ```
469
470 (Sidebar: that approach to authentication only works with fossil
471 versions newer than 2025-07-27, so the library cannot log in
472 to older fossil versions but can otherwise speak to them.)
473
474 The library guarantees that the same db transaction as was in
475 effect when ch->init() was called will be in place when this is
476 called.
477
478 Implementations must return 0 on success. On error,
479 implementations must return a non-FSL_RC_OK value from the
480 fsl_rc_e enum, and are strongly encouraged to set an error
481 message using the fsl_xfer_error() family of functions, passing
482 ch->xfer to it.
483 */
484 int (*submit)(fsl_sc *ch, fsl_buffer const *loginCard);
485
486 /**
487 Must read, or consume from its buffer, the requested amount of
488 data and append it to tgt. It must only append to the target
489 buffer, not reset or otherwise manipulate it, as the buffer may
490 already contain state when this is called.
491
492 If howMuch is greater than zero, it's a number of bytes which are
493 expected to be appended to tgt. A non-0 result code must be
494 returned if exactly that many bytes cannot be consumed.
495
496 If howMuch is FSL_SC_READ_LINE then:
497
498 1) One newline-separated (0x0A) line must read from the input
499 source and be append to tgt, including the newline character.
500 Aside from interpretation of that one character,
501 implementations must treat the preceeding data (if any) as
502 opaque. i.e. it must not be otherwise parsed and empty lines
503 must not be skipped.
504
505 2) If no newline is found, return FSL_RC_BREAK if at EOF and no
506 data precedes the EOF, else some other non-0 error code
507 (e.g. FSL_RC_IO). The library will interpret FSL_RC_BREAK as a
508 non-error EOF condition.
509
510 If howMuch is FSL_SC_READ_ALL then the library must read the
511 whole response into the target buffer. (This is used by the
512 library to handle fossil-compressed response bodies on behalf of
513 fsl_sc implementations.) If the implementation internally stores
514 the response in fsl_buffer, it should use fsl_buffer_swap() to
515 transfer it to tgt, rather than copy it. If it uses a file,
516 fsl_stream() can be used to transfer it, e.g.:
517
518 ```
519 fsl_stream(fsl_input_f_FILE, responseFile,
520 fsl_output_f_buffer, tgt);
521 // or:
522 fsl_stream(fsl_input_f_fd, &myFileDescriptor,
523 fsl_output_f_buffer, tgt);
524 ```
525
526 When howMuch is FSL_SC_READ_ALL, the library will not read any
527 more from the channel until/unless ch->submit() is called again,
528 so the implementation may free up any related resources at that
529 point if it likes.
530
531 The library will never pass a howMuch value of 0 to this
532 function, but it reserves the option of eventually using 0 as a
533 way of communicating that we are done reading, if such a
534 capability ever becomes useful. For future compatibility's sake,
535 it's legal to simply return 0 if howMuch is 0, but it's also
536 legal to assert(howMuch!=0) until that happens.
537
538 Must return 0 on success, non-0 on error, and should use one of
539 the fsl_xfer_error() family of functions to to provide any error
540 message and propagate the error through the library.
541 */
542 int (*read)(fsl_sc *ch, fsl_buffer * tgt, fsl_int_t howMuch);
543
544 /**
545 Must free up all dynamically-allocated resources owned by ch and
546 ch->impl.
547
548 Finalizing must, if appropriate, free up any resources it uses,
549 but must not free the object passed to it (which might be
550 stack-allocated or part of a larger struct). If this connection
551 is still open, it must close it.
552
553 It is up to the implementation to set ch->impl.p to 0 if that's
554 appropriate for them - the library does not do so. Some
555 implementations may use static state and not need to reset
556 ch->impl.
557
558 In the wisdom of "destructors must not throw," the library
559 provides no way to report a failure to close a channel (nor does
560 it really care, at that point - by then the channel will have
561 either already failed or served its purpose). If, after this
562 call, ch->f has error state, the library has the option, at its
563 developers' discretion, of emitting a warning to the client (this
564 is unspecified and currently unimplemented, but warning and/or
565 debug channels may be added at some point).
566
567 The library will never pass NULL to this function.
568
569 The library does not guaranty that a db transaction will be in
570 place when this is called.
571
572 This method must never be called directly from client
573 code. Instead, pass the object to fsl_sc_cleanup(), as that will
574 free up the common fsl_sc members, leaving clean() impls to only
575 concern themselves with their own private state.
576 */
577 void (*cleanup)(fsl_sc *ch);
578
579 /**
580 This is internal-use tooling to support adding "shim" layers of
581 fsl_sc between the library and the "real" fsl_sc. The default
582 impl (fsl_sc_self()) is suitable for all non-proxying channels
583 and simply returns its argument. The impl for the tracer channel
584 returns the object it's tracing. This distinction is relevant for
585 handing of fsl_sc internals such as ch->url and ch->flags, in
586 that (A) the internals always want those values to come from the
587 "real" implementation, not the shim, and (B) they don't want code
588 which is using a shim to have to know it's using a shim. Calling
589 ch->self(ch)->url will return the "correct" URL object.
590
591 Implementation code of a fsl_sc, unless that channel is itself a
592 proxy for another, should not use this - it's simply not needed
593 there. It's used by library code which wants to avoid having to
594 know there's a shim/proxy channel in place. Implementors of proxy
595 channels must provide a self() implementation which looks
596 something like the following (taken from the tracer channel):
597
598 ```
599 // Custom channel state, set in fsl_sc::impl.p of channels
600 // of this subtype.
601 struct my_channel_state {
602 fsl_sc * proxied; // proxied channel
603 ... any other necessary state ...
604 };
605 typedef struct my_channel_state my_channel_state;
606
607 fsl_sc * my_self(fsl_sc *ch){
608 my_channel_state * const st = ch->impl.p;
609 fsl_sc * const orig = st->proxied;
610 return orig->self(orig); // call self() in case orig is a proxy!
611 }
612 ```
613 */
614 fsl_sc * (*self)(fsl_sc *ch);
615
616 /**
617 If this->flags contains FSL_SC_F_REQUEST_HEADERS, the library
618 will populate this with raw HTTP headers for the request,
619 including a trailing `\r\n` line, immediately before calling
620 submit(). Implementations' submit() methods must, unless they do
621 their own header generation, emit this before the body. See
622 FSL_SC_F_REQUEST_HEADERS.
623 */
625 /**
626 A general-purpose scratchpad buffer for use by the channel object
627 and the library internals.
628 */
630}/*fsl_sc*/;
631
632/**
633 An implementation for fsl_xfer::debug::callback which requires
634 that the associated state be a (FILE*) handle opened for output.
635 Each call sends zMsg to that FILE handle via fprintf(), without
636 additional decoration.
637*/
638FSL_EXPORT void fsl_xfer_debug_f_FILE(fsl_xfer *xf, char const * zMsg);
639
640/**
641 An implementation for fsl_xfer::debug::callback which requires
642 that the associated state be a (fsl_buffer*). On each call zMsg is
643 appended as-is to that buffer, without additional decoration.
644*/
645FSL_EXPORT void fsl_xfer_debug_f_buffer(fsl_xfer *xf, char const * zMsg);
646
647/**
648 The default implementation of fsl_sc::self(). Simply returns
649 ch.
650*/
652
653/** Empty-initialized fsl_sc instance, intended for const-copy
654 initialization. */
655#define fsl_sc_empty_m { \
656 .xfer=0, .name="unnamed", \
657 .url=fsl_url_empty_m, \
658 .flags = 0, \
659 .impl = {.p = 0,.type = 0}, \
660 .init=0, .append = 0, \
661 .submit=0, \
662 .read=0, .cleanup=0, \
663 .self=fsl_sc_self, \
664 .requestHeaders = fsl_buffer_empty_m, \
665 .scratch = fsl_buffer_empty_m \
666}
667
668/** Empty-initialized fsl_sc instance, intended for copy
669 initialization. */
670extern const fsl_sc fsl_sc_empty;
671
672
673#if 0
674enum fsl_sync_e {
675 /* Adapted from fossil(1)'s xfer.c */
676 FSL_SYNC_PUSH = 1<<0, /* push content client to server */
677 FSL_SYNC_PULL = 1<<1, /* pull content server to client */
678 FSL_SYNC_BIDI = FSL_SYNC_PUSH | FSL_SYNC_PULL,
679 FSL_SYNC_CLONE = 1<<2, /* clone the repository */
680 FSL_SYNC_PRIVATE = 1<<3, /* Also transfer private content */
681 FSL_SYNC_VERBOSE = 1<<4, /* Extra diagnostics */
682 FSL_SYNC_RESYNC = 1<<5, /* --verily */
683 FSL_SYNC_DEBUG = 1<<6, /* Install a testing-only debug func in the channel */
684 FSL_SYNC_DRYRUN = 1<<7, /* roll back transaction when done */
685 FSL_SYNC_AUTO = 1<<8, /* use autosync setting */
686 //FSL_SYNC_FROMPARENT = 0x00040, /* Pull from the parent project */
687 //FSL_SYNC_UNVERSIONED = 0x00100, /* Sync unversioned content */
688 //FSL_SYNC_UV_REVERT = 0x00200, /* Copy server unversioned to client */
689 //FSL_SYNC_UV_TRACE = 0x00400, /* Describe UV activities */
690 //FSL_SYNC_UV_DRYRUN = 0x00800, /* Do not actually exchange files */
691 //FSL_SYNC_IFABLE = 0x01000, /* Inability to sync is not fatal */
692 //FSL_SYNC_CKIN_LOCK = 0x02000, /* Lock the current check-in */
693 //FSL_SYNC_NOHTTPCOMPRESS = 0x04000, /* Do not compression HTTP messages */
694 //FSL_SYNC_ALLURL = 0x08000, /* The --all flag - sync to all URLs */
695 //FSL_SYNC_SHARE_LINKS = 0x10000, /* Request alternate repo links */
696 //FSL_SYNC_XVERBOSE = 0x20000, /* Extra verbose. Network traffic */
697};
698#endif
699
700/**
701 Flags regarding which configuration options to sync.
702
703 This should probably be strings so that we don't have to adapt this
704 for every protocol addition.
705*/
708 FSL_CFG_SYNC_CSS = 1<<0, /* Style sheet only */
709 FSL_CFG_SYNC_SKIN = 1<<1, /* WWW interface appearance */
710 FSL_CFG_SYNC_TKT = 1<<2, /* Ticket configuration */
711 FSL_CFG_SYNC_PROJ = 1<<3, /* Project name */
712 FSL_CFG_SYNC_SHUN = 1<<4, /* Shun settings */
713 FSL_CFG_SYNC_USER = 1<<5, /* The USER table */
714 FSL_CFG_SYNC_ADDR = 1<<6, /* The CONCEALED table */
715 FSL_CFG_SYNC_XFER = 1<<7, /* Transfer configuration */
716 FSL_CFG_SYNC_ALIAS = 1<<8, /* URL Aliases */
717 FSL_CFG_SYNC_SUBSCRIBER = 1<<9, /* Email subscribers */
718 FSL_CFG_SYNC_IWIKI = 1<<10, /* Interwiki codes */
719 FSL_CFG_SYNC_ALL = 0x0000ffff, /* Everything */
720 FSL_CFG_SYNC_OVERWRITE = 0x10000000 /* Causes overwrite instead of merge */
721};
722
723/**
724 NOT YET IMPLEMENTED. This interface is experimental and subject to
725 change. The plan, however, is...
726
727 Fluid. The plan is fluid.
728
729 On success, returns 0, else it returns one of any number of
730 fsl_rc_e codes and may be propagating error information accessible
731 via fsl_cx_err_get().
732*/
734
735#if 0
736/**
737 Resets ch's buffers for re-use and then calls ch->submit().
738
739 This is prefered to calling ch->submit() directly because this
740 ensures that ch's buffers are accounted for.
741*/
742FSL_EXPORT void fsl_sc_close(fsl_sc * const ch);
743#endif
744
745/**
746 Calls fsl_sc_close() then, if ch->cleanup is not NULL, it is
747 called. Then it frees all of ch's buffers. Does not free ch.
748
749 This is prefered to calling ch->cleanup() directly because this
750 ensures that ch's buffers are accounted for.
751*/
753
754/**
755 If xf has a debug channel installed, the given
756 fsl_appendf()-compatible arguments are posted to it in string
757 form. The output may be prefixed with other information.
758
759 If xf has no debugging channel then this function has no
760 side-effects.
761
762 This function adds a newline to the result if it does not end in
763 one.
764
765 Returns 0 on success and the only error case is a formatting buffer
766 allocation error, which causes FSL_RC_OOM to be returned. Such
767 results should not be propagated by client code - an OOM is
768 innocuous in the context of debugging output.
769
770 This function requires allocating memory, and re-uses a buffer
771 dedicated to that purpose. In ideal cases, it won't have to
772 allocate more than once during the lifetime of a given fsl_xf
773 instance.
774
775 WARNING: fsl_xfer_config::debug-bound logging functions must not
776 call this, else there will be an endless loop and eventual stack
777 overflow.
778*/
779FSL_EXPORT int fsl_xfer_debugf(fsl_xfer * xf, char const * zFmt, ...);
780
781/** va_list variant of fsl_xfer_debugf(). */
782FSL_EXPORT int fsl_xfer_debugfv(fsl_xfer * xf, char const * zFmt, va_list args);
783
784/**
785 Equivalent to fsl_xfer_debugf(ch,"%s",zMsg) but is more efficient
786 than that.
787*/
788FSL_EXPORT void fsl_xfer_debug(fsl_xfer * xf, char const * zMsg);
789
790/**
791 Returns xf's fsl_cx context. This is used in fsl_sc callback
792 implementations.
793*/
795
796/**
797 Sets xf's (persistent) error state to the given information
798 and propagates it through to xf's fsl_cx. After this,
799 further calls to fsl_xf-taking APIs will fail.
800
801 This is intended to only be used from fsl_sc implementations
802 and this library's own internals.
803
804 This function prefixes the message with some form of ch->name and
805 the fsl_rc_cstr() value of the given result code.
806
807 Returns the given code, or FSL_RC_ERROR if code is 0. i.e.
808 it never returns 0. A code value of 0 is semantically illegal in
809 this context.
810*/
811FSL_EXPORT int fsl_xfer_errorf(fsl_xfer *xf, int code, char const * zFmt,
812 ...);
813
814/** va_list variant of fsl_xfer_errorf(). */
815FSL_EXPORT int fsl_xfer_errorfv(fsl_xfer *xf, int code, char const * zFmt,
816 va_list args);
817
818/**
819 Equivalent to fsl_xfer_errorf(ch,code,"%s",zMsg) but more
820 efficient.
821*/
822FSL_EXPORT int fsl_xfer_error(fsl_xfer *xf, int code, char const * zMsg);
823
824
825/**
826 Policies for use with fsl_sc_popen indicating how to fetch the
827 response from invoking an external command to transport fossil sync
828 requests. This is all internal experimentation, not part of the
829 public API.
830*/
832 /**
833 Directs the binary's stdout to a temp file bound to
834 fsl_sc_popen_state::response::fp using fopen().
835
836 This "should" work the same as fsl_sc_popen_e_direct but this one
837 works where that one doesn't, for reasons unknown.
838
839 Measurements show, somewhat surprisingly, this to be
840 significantly faster than fsl_sc_popen_e_membuf (anywhere from
841 30% to twice as fast, depending on the test run), as well as far
842 memory-lighter: 410kb peak RAM vs 9.4MB peak ram for the same
843 clone of fossil's canonical repository.
844 */
846
847 /**
848 Don't use this except for experimentation.
849
850 Slurp whole response into a fsl_buffer at
851 fsl_sc_popen_state::response. This works but can use a huge
852 amount of memory.
853
854 This is slower than fsl_sc_popen_e_filebuf and much more
855 memory-hungry. The main speed culprit seems to be
856 fsl_buffer_stream_lines(), which takes up some 25% of the test
857 run's CPU instructions (as reported by callgrind).
858 */
859
861
862 /**
863 Does not work!
864
865 Don't buffer: read response from the binary's stdout, bound to
866 fsl_sc_popen_state::process::fdStdOut.
867
868 This mode is currently failing with curious read failures: for
869 _some_ cards, reading the payload leaves (apparently) pieces
870 which are then read by the next read-line op and of course don't
871 parse as a card. The cause is as-yet unknown but it's got to be a
872 bug somewhere in this code.
873 */
875
876 /**
877 Does not work!
878
879 Read the binary's stdout using an unbuffered file descriptor
880 open()ed on fsl_sc_popen_state::response::fd.
881
882 This is is known to fail with "not found" for the output file
883 after fsl_popen2()'ing the command (at which point we expect the
884 output to be there). This "should" fail in the same way as
885 fsl_sc_popen_e_direct, as we're doing the same thing just with
886 another file of indirection.
887 */
889
890 /**
891 Mode used by fsl_sc_popen_state_empty.
892 */
894};
895
897
898/**
899 State for use with the fsl_sc_popen fsl_sc impl. fsl_sc_popen
900 requires that its state member point to an instance of this class.
901
902 This type acts as a base implemtation for channels which
903 "shell out" to an external binary to provide the transport
904 layer. e.g. curl can be used for HTTP(S) and fossil(1)'s own
905 "test-http" mechanism can be used this way.
906*/
908 /**
909 State for "subclasses". Not really subclasses, but "concrete
910 implementations" gets unwieldy after a while.
911 */
912 struct {
913 /**
914 This optional method gets called as part of the
915 FSL_SC_INIT_INITIAL phase of fsl_sc::init() to give subclasses
916 a way to perform any validation they may need. It may also
917 perform any one-time initialization it may need to do.
918
919 If it returns non-0, channel initialization fails.
920 */
921 int (*init)(fsl_sc *ch);
922
923 /**
924 Command arguments initializer. Must be set by concrete
925 implementations and it gets invoked via
926 fsl_sc::submit(). Implementations must populate b using
927 ((fsl_sc_popen_state*)ch->impl.p)'s state, namely the
928 request.filename and response.filename members, which are names
929 of temporary files which will eventually contain the request
930 payload and response payloads.
931
932 Implementations must use fsl_buffer_escape_arg() and friends to
933 append a complete command line to b. They must return 0 on
934 success.
935
936 When this is called (early on in the fsl_sc::submit() process):
937
938 - this->bin.location will be set to the command to invoke. It
939 must be prepended to the command line (or may it may be
940 proxied via a separate command known only to the concrete
941 implementation).
942
943 - this->url will be set to the remote fossil URL.
944
945 - this->request.filename is a file which the
946 command is expected to read the fossil sync request body
947 payload from.
948
949 - If this->response.filename is not NULL then it is a file
950 which the command is expected to write the fossil sync
951 response to, minus any transport-layer metadata like HTTP
952 headers. If it is NULL, the process is expected to write to
953 stdout.
954
955 - None of the other this->request and this->response members
956 will be set up.
957
958 - If bLoginCard is not NULL then it will hold the content for a
959 fossil sync login card. Implementations must emit an HTTP
960 header in the form "Cookie: x-f-x-l=XYZ" where XYZ is the
961 URL-encoded content of bLoginCard. For fsl_sc impls which
962 use the FSL_SC_F_REQUEST_HEADERS flag, the library will have
963 populated ch->requestHeaders before this is called, including
964 the login card.
965 */
967 fsl_buffer const * bLoginCard);
968
969 /**
970 May be set for subclasses in order to clean up any dynamic
971 state owned by this object in this->impl.state. It will be
972 called early in the fsl_sc::cleanup() step, before st's base
973 class state are cleaned.
974
975 Whether or not it must free st is implementation-defined.
976 */
978
979 /**
980 Subclass-specific state. Owned by this object's cleanup()
981 method.
982 */
983 void * state;
985
986 /** Info about the binary. */
987 struct {
988 /**
989 The name of the program binary, e.g. "curl". It is expected to
990 be findable via the $PATH.
991 */
992 char const * name;
993 /**
994 Location where the binary was found. If NULL, it defaults to a
995 $PATH search of this->bin.name. Clients may set this before
996 use, but (A) it must be allocated using a libfossil API,
997 e.g. fsl_mprintf(), and (B) this memory is owned by this
998 object.
999
1000 If the client does not set this, the library will search in the
1001 $PATH for this->name and assign that value here.
1002 */
1003 char * location;
1005 /** State for/around fsl__popen2(). */
1006 struct {
1007 /** The external process's stdin, i.e. a write-only stream. */
1008 FILE *fStdIn;
1009 /** The external process's stdout, i.e. a read-only stream. */
1011 /** The external process's PID. */
1012 int pid;
1014
1015 /**
1016 State for the sync request payload.
1017 */
1018 struct {
1019 /** Filename of this->fp. */
1021 /** Request payload temp file. */
1022 FILE *fp;
1023 /** Number of initiated requests. */
1024 unsigned count;
1026
1027 /**
1028 State for the sync response payload.
1029 */
1030 struct {
1031 /**
1032 How to read the response. This should never be set by clients.
1033 It's for library-internal experimentation. If it must be set as
1034 part of a struct initialization, set it to
1035 fsl_sc_popen_e_default.
1036 */
1038 /**
1039 Response temp file when this->response.mode is
1040 fsl_sc_popen_e_filebuf or fsl_sc_popen_e_fd.
1041 */
1042 char *filename;
1043 /**
1044 Response source file when this->mode is fsl_sc_popen_e_filebuf.
1045 This file is opened in "w+b" mode.
1046 */
1047 FILE * fp;
1048 /**
1049 Response input source when this->mode is fsl_sc_popen_e_fd.
1050 */
1051 int fd;
1052 /** Number of initiated response-reads. */
1053 unsigned count;
1054 /**
1055 Response body when this->mode is fsl_sc_popen_e_membuf.
1056 */
1059
1060 /**
1061 Flag(s).
1062 */
1063 struct {
1064 /**
1065 Internal implementation detail. Tells fsl_sc_popen's
1066 cleanup() impl whether or not to free() this object.
1067 */
1069
1070 /**
1071 A random prefix for temp file names. Memory is owned by this
1072 object. All request and response temp files are prefixed with
1073 this and get a predictable suffix. We generate a random prefix,
1074 rather than a new random name on each call, to simplify
1075 grouping of the files for development and debugging purposes.
1076 */
1079
1080 /**
1081 The command line to invoke. This is intended to be set up by
1082 this->impl.buildCommandLine.
1083 */
1085};
1086
1087/**
1088 Initializer for a fsl_sc_popen_state object which sets
1089 obj.bin.name=BinName, obj.impl.buildCommandLine=XCmdInit, and
1090 obj.impl.cleanup=XCleanup.
1091
1092 The object is intended only for use as the fsl_sc::state pointer of
1093 a copy of fsl_sc_popen.
1094*/
1095#define fsl_sc_popen_state_init(BinName,xInit,XCmdInit,XCleanup) { \
1096 .impl = { \
1097 .init=xInit, \
1098 .buildCommandLine=XCmdInit, \
1099 .cleanup=XCleanup, .state = 0 \
1100 }, \
1101 .bin = { .name = BinName, .location = 0 }, \
1102 .process = { \
1103 .fStdIn = 0, .fdStdOut = -1, .pid = 0 \
1104 }, \
1105 .request = { \
1106 .filename = 0, .fp = 0, .count=0 \
1107 }, \
1108 .response = { \
1109 .mode = fsl_sc_popen_e_default, \
1110 .filename = 0, .fp = 0, .fd = -1, \
1111 .count=0, .b = fsl_buffer_empty_m \
1112 }, \
1113 .misc = { \
1114 .allocStamp = 0, \
1115 .tmpfilePrefix = 0 \
1116 }, \
1117 .cmd = fsl_buffer_empty_m \
1118}
1119
1120//#define fsl_sc_popen_state_empty_m fsl_sc_popen_state_init("unnamed",0,0)
1121
1122/**
1123 An empty base fsl_sc_popen_state instance intended to be
1124 copied to intialize fsl_sc_popen_state implementations.
1125 Implementations must set the bin.name and
1126 impl.buildCommandLine members to whatever is appropriate for the
1127 object's external binary.
1128*/
1130
1131/**
1132 An empty base fsl_sc instance for use with fsl_sc_popen_state
1133 implementations.
1134
1135 To use it:
1136
1137 1. Bitwise-copy it over a fsl_sc instance.
1138
1139 2. Set its state.p member to point to a valid fsl_sc_popen_state
1140 instance.
1141
1142 3. Do not modify its state.type member.
1143
1144 Nuances of this implementation:
1145
1146 - Its state.p _must_ be a (fsl_sc_popen_state*) and state.type must
1147 be &fsl_sc_popen. This initializer does that latter part.
1148
1149 - If state->flag.allocStamp is not 0, it must point to state->p.
1150 This indicates that this object owns its state pointer and will
1151 free it via this object's cleanup() method.
1152*/
1153extern const fsl_sc fsl_sc_popen;
1154
1155/**
1156 An empty state object of the type expected by fsl_sc_popen,
1157 configured to use the system's "curl" binary as the fossil sync
1158 communication channel.
1159*/
1161
1162/**
1163 Like fsl_sc_popen but may include different fsl_sc::flags defaults.
1164 The state.p member _must_ point to a fsl_sc_popen_state instance
1165 initialized by bitwise copying from fsl_sc_popen_state_curl.
1166
1167 Example usage:
1168
1169 ```
1170 fsl_sc_popen_state pst = fsl_sc_popen_state_curl;
1171 fsl_sc st = fsl_sc_popen_curl;
1172 st.state.p = &pst;
1173 ```
1174*/
1175extern const fsl_sc fsl_sc_popen_curl;
1176
1177/**
1178 Works like fsl_sc_popen_curl but uses "fossil test-http" for the
1179 transport layer. The fsl_sc::state::p pointer of these objects MUST be a
1180 pointer to an fsl_sc_popen_state object which was initialized by
1181 copying it from fsl_sc_popen_state_fth. Example:
1182
1183 ```
1184 fsl_sc sc = fsl_sc_popen_fth;
1185 fsl_sc_popen_state st = fsl_sc_popen_state_fth;
1186 sc.state.p = &sc;
1187 ```
1188*/
1189extern const fsl_sc fsl_sc_popen_fth;
1190/**
1191 State type for use with fsl_sc_popen_fth.
1192*/
1194
1195/**
1196 Works like fsl_sc_popen_curl but uses "ssh ... fossil test-http" for the
1197 transport layer. The fsl_sc::state::p pointer of these objects MUST be a
1198 pointer to an fsl_sc_popen_state object which was initialized by
1199 copying it from fsl_sc_popen_state_ssh. Example:
1200
1201 ```
1202 fsl_sc sc = fsl_sc_popen_ssh;
1203 fsl_sc_popen_state st = fsl_sc_popen_state_ssh;
1204 sc.state.p = &sc;
1205 ```
1206
1207 By default it assumes that fossil(1) is in the remote's $PATH, but
1208 it can be explicitly told the path by providing a query argument to
1209 the URL: fossil=/path/to/remote/fossil (URL-encoded if it contains
1210 anything which needs to be).
1211
1212 Peculiarities of this implementation:
1213
1214 - Any password part of the URL is used as the remote fossil
1215 password, not the SSH password. The URL part is stripped before
1216 passing the URL on to ssh. However, fossil does not honor logins
1217 over ssh (the user is given full admin access), so applying the
1218 fossil login card here is a matter of conscience and
1219 library-level consistency, not one of necessity.
1220*/
1221extern const fsl_sc fsl_sc_popen_ssh;
1222
1223/**
1224 State type for use with fsl_sc_popen_ssh.
1225*/
1227
1228/**
1229 Expands to a mapping of all fsl_sc_tracer_e types by invoking
1230 E(NAME,VALUE) for each one. NAME is the suffix part of the name,
1231 e.g. init instead of FSL_SC_TRACER_init. VALUE is its integer
1232 value.
1233*/
1234#define fsl_sc_tracer_map(E) \
1235 E(none,0) \
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) \
1238 E(debug, 1<<6)
1239
1241#define E(NAME,FLAG) FSL_SC_TRACER_ ## NAME = FLAG,
1243#undef E
1244
1245 FSL_SC_TRACER_all = 0
1246#define E(NAME,FLAG) | FSL_SC_TRACER_ ## NAME
1248#undef E
1249
1250 FSL_SC_TRACER_default = FSL_SC_TRACER_init
1251 | FSL_SC_TRACER_cleanup
1252 | FSL_SC_TRACER_submit
1253 | FSL_SC_TRACER_self
1254};
1255
1256/**
1257 An fsl_sc implementation which proxies another, which must be
1258 set as its state member.
1259
1260 This proxy calls fsl_sc_debug() with the name of each called fsl_sc
1261 method before passing the method on to the proxied changed.
1262
1263 The exception is: the fsl_sc::debug.callback method is passed that
1264 through directly because calling fsl_sc_debug() on itself leads to
1265 an endless loop.
1266
1267 Example:
1268
1269 ```
1270 fsl_sc orig = ...some other sc...;
1271 fsl_sc tracer = fsl_sc_tracer_empty;
1272 fsl_sc_tracer_init(&tracer, &orig);
1273 ```
1274
1275 Then use tracer in place of orig with the downstream APIs. Calling
1276 tracer.cleanup(&tracer) will also cleanup orig.
1277
1278 To customize where the debug messages go, replace the object's
1279 debug.callback method with one which expects an object of this type
1280 and emit them from there wherever you like. Just don't call any of
1281 the fsl_sc_debug() family of functions on that object, else an
1282 endless debig call loop will trigger.
1283*/
1284extern const fsl_sc fsl_sc_tracer_empty;
1285
1286/**
1287 Initializes chTrace as a copy of fsl_sc_tracer_empty then directs
1288 chTrace's state to point to ch. Returns chTrace on success. On
1289 error it returns NULL.
1290*/
1292 fsl_flag32_t traceFlags,
1293 fsl_outputer * out);
1294
1295/** @internal
1296
1297 Pass the name of a macro which takes 2 arguments to this
1298 macro. Macro E will be called with (NAME,LENGTH) of each sync card
1299 type. NAME is the unquoted name. LENGTH is strlen(#NAME) (which we
1300 need in a compile-time form).
1301
1302 !!! Keep these sorted by name and edit code which uses these to
1303 !!! match. Internals require them to be sorted by name. Actually...
1304 !!! maybe not anymore.
1305*/
1306#define fsl_xfcard_map(E) \
1307 /* KEEP */ E(cfile,5) E(clone,5) E(clone_seqno,11) E(config,6) \
1308 /* THESE */ E(cookie,6) E(error,5) E(file,4) E(gimme,5) E(igot,4) \
1309 /* SORTED */ E(login,5) E(uvfile,6) E(message,7) E(pragma,6) \
1310 /* BY */ E(private,7) E(pull,4) E(push,4) E(reqconfig,9) \
1311 /* NAME */ E(uvgimme,7) E(uvigot,6)
1312
1313/** @internal
1314
1315 Ids for fossil sync protocol card types.
1316*/
1318 /* MUST BE FIRST. Reminder to self: this has to be outside of
1319 fsl_xfcard_map() because of how fsl__xfcard_search() is set up. */
1321
1322#define E(T,LEN) fsl_xfcard_e_ ## T,
1324#undef E
1325
1326 /* Sentinel entry */
1327 fsl_xfcard_e_COUNT
1328};
1330/**
1331 A comma-separated list of zeroes: one for each entry in
1332 fsl_xfcard_e.
1333*/
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
1336
1337/**
1338 Metrics for use with the library's "xfer" (sync) subsystem.
1339*/
1341 /** Number of connections made to the remote. */
1343 /** Number of "igot" cards sent */
1345 /** Number of private "igot" cards */
1347 /** Number of gimme cards sent */
1349 /** Number of files sent */
1351 /** Number of deltas sent */
1353 /** Number of files received */
1355 /** Number of deltas received */
1357 /** Number of dangling deltas received */
1359 /** Total received artifacts */
1361 /** Total received cards */
1363 /** Total sent cards */
1365 /** Largest card payload size */
1367 /**
1368 Buffer capacity allocated for the latest single
1369 fossil-compressed response.
1370 */
1372 /**
1373 Number of compressed response bytes via fsl__xfer_submit().
1374 This counts only compressed response bodies, not the compressed
1375 content of cfile cards.
1376 */
1378 /** Number of uncompressed response bytes via fsl__xfer_read() and
1379 fsl_xfer_readln(). */
1381 /** Number of bytes via fsl__xfer_append() and friends. */
1383 /** Counts of each card type seen in the response(s). */
1384 fsl_size_t cardsRx[fsl_xfcard_e_COUNT];
1385 /**
1386 Counts of each card type sent in request(s).
1387
1388 TODO: replace most of the card-specific members with this. We
1389 first need to change how fsl__xfer_appendln() works.
1390 */
1391 fsl_size_t cardsTx[fsl_xfcard_e_COUNT];
1392
1393 /** Various timing metrics. */
1394 struct {
1395 /** Time spent waiting on fsl_sc::read(), but only via
1396 fsl__xfer_read(), fsl__xfer_readln(), and (when reading
1397 compressed responses) fsl__xfer_submit(). */
1399 /** Time spent waiting on fsl_sc::submit(). */
1401 /**
1402 Time taken to decompress cfile card payloads.
1403 */
1405 /**
1406 Time taken to decompress cfile card payloads.
1407 */
1410};
1411
1413
1414/**
1415 Empty-initialized fsl_xfer_metrics instance intended for
1416 const-copy initialization.
1417*/
1418#define fsl_xfer_metrics_empty_m { \
1419 .trips = 0, \
1420 .iGotSent = 0, \
1421 .privIGot = 0, \
1422 .gimmeSent = 0, \
1423 .fileSent = 0, \
1424 .deltaSent = 0, \
1425 .fileRcvd = 0, \
1426 .deltaRcvd = 0, \
1427 .danglingFile = 0, \
1428 .rcvdArtifacts = 0, \
1429 .rcvdCards = 0, \
1430 .sentCards = 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}, \
1438 .timer = { \
1439 .read = fsl_timer_empty_m, \
1440 .submit = fsl_timer_empty_m, \
1441 .uncompress = fsl_timer_empty_m, \
1442 .process = fsl_timer_empty_m \
1443 } \
1444 }
1445
1446/**
1447 Empty-initialized fsl_xfer_metrics instance intended for
1448 non-const copy initialization.
1449*/
1451
1452/**
1453 A callback for use with the libfossil sync transfer subsystem.
1454 Implementations are passed the sync-related metrics, their state
1455 object, and the result code of the sync (so that they can choose
1456 whether or not to skip any display on error).
1457*/
1458typedef void (*fsl_xfer_metrics_f)(fsl_xfer_metrics const *, void*,
1459 int theRc);
1460
1461/**
1462 A fsl_xfer_metrics_f implementation which requires that its second
1463 argument be a (fsl_xfer_metrics*). It copies the first argument
1464 bitwise over the second. The final argument is ignored.
1465*/
1466void fsl_xfer_metrics_f_dup(fsl_xfer_metrics const *, void*, int theRc);
1467
1468/**
1469 A fsl_xfer_metrics_f implementation which requires its second
1470 argument to be a (fsl_outputer*). It sends all output to that
1471 channel. If theRc is non-0 then this is a no-op.
1472*/
1474 void *state, int theRc);
1475
1476/**
1477 This typedef describes a callback used by the library for fetching
1478 passwords when needed for remote synchronization.
1479
1480 Its first two arguments are current fsl_cx and the URL the password
1481 is being requested for. The final argument is
1482 implementation-dependent state.
1483
1484 Implementations must somehow collect a password for the given URL,
1485 append a copy of it to bPout, and return 0 on success. On error
1486 they must return non-0, preferably the result of passing f to
1487 fsl_cx_err_set(). If appending the result to the buffer fails, it's
1488 caused (barring invalid arguments) by an OOM, in which case that
1489 code can be returned directly.
1490
1491 It is legal for implementations to use bOut for construct their
1492 input prompt, so long as they pass it to fsl_buffer_reuse() before
1493 appending the password to it.
1494
1495 To indicate a non-error when no password is available, return 0 and
1496 do not modify bOut (or pass it to fsl_buffer_reuse() before
1497 returning). In such cases the library will continue as if no
1498 credentials are available, which might trigger an error later on if
1499 credentials are required.
1500
1501 bOut is owned by the library. The state argument is owned by
1502 whoever put it there.
1503
1504 Design notes:
1505
1506 Sync passwords are stored, if at all, in f's global config
1507 database. Each has a key of "libfossil-sync-pw:" + the URL shorn
1508 of any password part. Thus saving a password for
1509 "http://foo:bar@baz/bar" will leave a config entry named
1510 "libfossil-sync-pw:http://foo@baz/bar". The passwords are stored as
1511 conventionally-fossil-hashed passwords.
1512
1513 Passwords are specific to a given repository "project-code", so
1514 attempting to sync to the same URL for multiple project codes will
1515 leave the sync unable to log in to any but the most recent one for
1516 which the password was saved.
1517
1518 This password storage is different from fossil(1)'s. The thinking
1519 is "separate apps, separate passwords", though the passwords all go
1520 in the same database. That's subject to change, though.
1521*/
1522typedef int (*fsl_pw_f)(fsl_cx * f, char const * zUrl,
1523 fsl_buffer * bOut, void * state);
1524
1525#if 0
1526/**
1527 A fsl_pw_f() implementation which uses unistd.h's
1528 obsolete/deprecated getpass(2). This implementation exists
1529 primarily for testing.
1530
1531 Warning: getpass(2) uses static state, so this function must not be
1532 used if multiple threads might need to use getpass(2).
1533
1534 This function works only for terminal applications, not GUI apps or
1535 those which cannot read from stdin.
1536
1537 This implementation ignores the final argument.
1538
1539
1540 TODO: implement a getpass()-free alternative like the one
1541 demonstrated at:
1542
1543 https://www.gnu.org/software/libc/manual/html_node/getpass.html
1544
1545 Ah, fossil(1) has one in its user.c as well.
1546*/
1547int fsl_pw_f_getpass(fsl_cx * f, char const * zUrl,
1548 fsl_buffer * bOut, void * state);
1549#endif
1550
1551/**
1552 Various configuration pieces for libfossil sync transfer subsystem.
1553*/
1555 /**
1556 The URL or filename to sync with. If this is NULL then the
1557 library will try to determine it from the currently-opened
1558 repository.
1559 */
1560 char const * url;
1561
1562 /**
1563 NYI! Max amount of time, in seconds, to spend generating a single
1564 response.
1565 */
1567
1568 /**
1569 NYI! Approximate max size, in bytes, for outbound response
1570 payloads. It may overstep this amount by a single artifact
1571 (which may be arbitrarily large).
1572 */
1574
1575 /**
1576 Verbosity level (higher is more verbose).
1577 */
1579
1580 /**
1581 A hint for fsl_sc channels which support it. See
1582 FSL_SC_F_LEAVE_TEMP_FILES.
1583 */
1585
1586 /**
1587 If true, use the application/x-fossil-uncompressed Content-Type
1588 for communication, else use application/x-fossil (which fossil
1589 does not compress). This is a _hint_ to the server, which may
1590 response how it likes.
1591
1592 NYI is compression of outbound traffic.
1593 */
1595
1596 /**
1597 When a sync operation happens on a transient fs_cx instance,
1598 e.g. during a clone operation into a new fsl_cx, this listener
1599 gets installed in the transient fsl_cx. Sync operations which
1600 happen in the context of a specific fsl_cx currently use that
1601 instance's message listener. "The plan" is to eventually allow an
1602 override of the listener for sync-specific messages, but that is
1603 not yet in place.
1604 */
1606
1607 /** Optional debug message callback. */
1609
1610 /**
1611 fsl_sc API tracing hook.
1612 */
1613 struct {
1614 /**
1615 If non-zero, a tracing channel is installed with the given mask
1616 of fsl_sc_tracer_e flags. If it is zero, no tracer is
1617 installed.
1618 */
1620 /**
1621 The output sink.
1622 */
1625
1626 /**
1627 Members which are set to true will activate
1628 specific aspects of sync.
1629 */
1630 struct {
1631 /* Clone with protocol version 1, 2, or 3. */
1632 short clone;
1633 /* Push content. */
1634 bool push;
1635 /* Pull content. */
1636 bool pull;
1637 /* Transfer private content. */
1639 /* Ignore push/pull/clone and use the autosync setting. */
1641 /* Request all igot cards from the server. */
1644
1645 struct {
1646 /**
1647 If not NULL, fsl__xfer's cleanup routine will call this,
1648 passing it the metrics, this->state, and the final result code
1649 of the sync process.
1650 */
1652 /**
1653 Optional state for the 2nd argument to this->callback(). It is
1654 owned by whoever assigns it to non-NULL.
1655 */
1656 void * state;
1658
1659 struct {
1660 /**
1661 Callback to use to fetch passwords.
1662 */
1664 /**
1665 State for the password callback. It must match that
1666 implementation's expectations.
1667 */
1668 void * state;
1669 /**
1670 If true:
1671
1672 - If the URL contains a password, then on successful sync
1673 the hashed password is saved for future use with that same
1674 URL (excluding the password part).
1675
1676 - If the URL has no password but a saved one is found, it is
1677 used.
1678 */
1679 bool save;
1681};
1682
1684
1685/**
1686 Empty-initialized fsl_xfer_config instance intended for const-copy
1687 initialization.
1688*/
1689#define fsl_xfer_config_empty_m { \
1690 .url = 0, \
1691 .maxResponseSeconds = -1, \
1692 .maxResponseBytes = 2500000, \
1693 .verbosity = 0, \
1694 .compressTraffic=false, \
1695 .listener = fsl_msg_listener_empty_m, \
1696 .debug = fsl_xfer_dbg_empty_m, \
1697 .trace = { \
1698 .mask = 0, \
1699 .outputer = fsl_outputer_FILE_m \
1700 }, \
1701 .op = { \
1702 .clone = 0, \
1703 .push = false, \
1704 .pull = false, \
1705 .privateContent = false, \
1706 .autosync = false \
1707 }, \
1708 .metrics = { \
1709 .callback = NULL, .state = NULL \
1710 }, \
1711 .password = { \
1712 .callback = NULL, \
1713 .state = NULL, \
1714 .save = false \
1715 } \
1716}
1717
1718/**
1719 Empty-initialized fsl_xfer_config instance intended for
1720 non-const-copy initialization.
1721*/
1723
1724/**
1725 Frees any memory which may be owned by p but does not
1726 free p.
1727*/
1729
1730/**
1731 Options for use with fsl_clone().
1732*/
1734 /** Options for fsl_repo_create(). */
1736 /**
1737 Options related to the transfer subsystem.
1738 */
1739 /** Core sync subsystem options. */
1741};
1742
1744
1745/**
1746 Empty-initialized fsl_clone_config instance intended for const-copy
1747 initialization.
1748*/
1749#define fsl_clone_config_empty_m { \
1750 .repo = fsl_repo_create_opt_empty_m, \
1751 .xfer = fsl_xfer_config_empty_m \
1752}
1753
1754/**
1755 Empty-initialized fsl_clone_config instance intended for
1756 non-const-copy initialization.
1757*/
1759
1760/**
1761 Under construction.
1762*/
1763int fsl_clone( fsl_clone_config const * cc, fsl_error * err );
1764
1765#if 0
1766/**
1767 Untested, incomplete, and it open design question remain regarding
1768 handling of the channel's state object's memory.
1769
1770 Attempts to find a fsl_sc class capable of handling the given
1771 fossil URL.
1772
1773 Currently handled:
1774
1775 - http and https: uses fsl_sc_popen
1776
1777 On success, returns a new instance, which the caller must
1778 eventually pass to fsl_sc_cleanup() and then to fsl_free().
1779*/
1780fsl_sc * fsl_sc_for_url( char const * zUrl );
1781#endif
1782
1783#if defined(__cplusplus)
1784} /*extern "C"*/
1785#endif
1786#endif
1787/* ORG_FOSSIL_SCM_FSL_SYNC_H_INCLUDED */
uint64_t fsl_size_t
fsl_size_t is an unsigned integer type used to denote absolute ranges and lengths.
Definition config.h:192
uint32_t fsl_flag32_t
A 32-bit unsigned int type.
Definition config.h:154
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...
Definition config.h:143
#define FSL_EXPORT
Definition config.h:66
This file declares the core SCM-related public APIs.
#define E(N, V, H)
Definition core.h:497
struct fsl__xfer fsl_xfer
A "transfer context" type used by many of the sync transfer APIs.
Definition core.h:732
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...
Definition util.h:684
Options for use with fsl_clone().
Definition sync.h:1733
fsl_xfer_config xfer
Options related to the transfer subsystem.
Definition sync.h:1740
fsl_repo_create_opt repo
Options for fsl_repo_create().
Definition sync.h:1735
The main Fossil "context" type.
Definition internal.h:400
A container for storing generic error state.
Definition util.h:781
Client callback info for receiving various events during fossil sync processing.
Definition core.h:803
An interface which encapsulates data for managing an output destination, primarily intended for use w...
Definition util.h:337
Configuration parameters for fsl_repo_create().
Definition repo.h:4167
State for use with the fsl_sc_popen fsl_sc impl.
Definition sync.h:907
struct fsl_sc_popen_state::@047271017132162232375350103101020026106103313371 impl
State for "subclasses".
FILE * fp
Request payload temp file.
Definition sync.h:1022
char * filename
Filename of this->fp.
Definition sync.h:1020
FILE * fStdIn
The external process's stdin, i.e.
Definition sync.h:1008
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...
Definition sync.h:921
void * allocStamp
Internal implementation detail.
Definition sync.h:1068
struct fsl_sc_popen_state::@266006325223237141160063003276124156214251367351 bin
Info about the binary.
unsigned count
Number of initiated requests.
Definition sync.h:1024
int(* buildCommandLine)(fsl_sc *ch, fsl_buffer *b, fsl_buffer const *bLoginCard)
Command arguments initializer.
Definition sync.h:966
char * tmpfilePrefix
A random prefix for temp file names.
Definition sync.h:1077
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.
Definition sync.h:1057
struct fsl_sc_popen_state::@066143155145161020053303036043160147002317037320 request
State for the sync request payload.
void * state
Subclass-specific state.
Definition sync.h:983
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....
Definition sync.h:977
char const * name
The name of the program binary, e.g.
Definition sync.h:992
fsl_buffer cmd
The command line to invoke.
Definition sync.h:1084
char * location
Location where the binary was found.
Definition sync.h:1003
int fd
Response input source when this->mode is fsl_sc_popen_e_fd.
Definition sync.h:1051
int fdStdOut
The external process's stdout, i.e.
Definition sync.h:1010
struct fsl_sc_popen_state::@146344352027260375167101145077256277014053205264 misc
Flag(s).
int pid
The external process's PID.
Definition sync.h:1012
struct fsl_sc_popen_state::@160202264027050270357317003235201000205071030176 response
State for the sync response payload.
enum fsl_sc_popen_e mode
How to read the response.
Definition sync.h:1037
The fsl_sc class encapsulates a streamable (as opposed to random-access) I/O channel intended solely ...
Definition sync.h:312
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.
Definition sync.h:439
int(* read)(fsl_sc *ch, fsl_buffer *tgt, fsl_int_t howMuch)
Definition sync.h:542
fsl_buffer scratch
A general-purpose scratchpad buffer for use by the channel object and the library internals.
Definition sync.h:629
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.
Definition sync.h:484
void const * type
An optional value which uniquely identifies with a specific type.
Definition sync.h:364
fsl_xfer * xfer
The "transfer context" for this channel.
Definition sync.h:318
char const * name
A debugging-purposes name for this channel, e.g.
Definition sync.h:325
fsl_buffer requestHeaders
If this->flags contains FSL_SC_F_REQUEST_HEADERS, the library will populate this with raw HTTP header...
Definition sync.h:624
void(* cleanup)(fsl_sc *ch)
Must free up all dynamically-allocated resources owned by ch and ch->impl.
Definition sync.h:577
void * p
Arbitrary state for implementations.
Definition sync.h:357
fsl_flag32_t flags
Flags for customizing certain behaviors.
Definition sync.h:344
fsl_url url
The remote fossil URL.
Definition sync.h:339
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...
Definition sync.h:413
State for the fsl_timer_xxx() family of functions.
Definition util.h:5447
A type for parsing URLs.
Definition util.h:6512
Various configuration pieces for libfossil sync transfer subsystem.
Definition sync.h:1554
fsl_msg_listener listener
When a sync operation happens on a transient fs_cx instance, e.g.
Definition sync.h:1605
bool leaveTempFiles
A hint for fsl_sc channels which support it.
Definition sync.h:1584
int32_t maxResponseBytes
NYI!
Definition sync.h:1573
void * state
Optional state for the 2nd argument to this->callback().
Definition sync.h:1656
char const * url
The URL or filename to sync with.
Definition sync.h:1560
struct fsl_xfer_config::@373075157177271020150144310017273005255063000152 trace
fsl_sc API tracing hook.
bool save
If true:
Definition sync.h:1679
fsl_outputer outputer
The output sink.
Definition sync.h:1623
fsl_xfer_dbg debug
Optional debug message callback.
Definition sync.h:1608
struct fsl_xfer_config::@064076272252252201345077146365363164074334354076 metrics
bool privateContent
Definition sync.h:1638
bool compressTraffic
If true, use the application/x-fossil-uncompressed Content-Type for communication,...
Definition sync.h:1594
short verbosity
Verbosity level (higher is more verbose).
Definition sync.h:1578
short clone
Definition sync.h:1632
int8_t maxResponseSeconds
NYI!
Definition sync.h:1566
bool autosync
Definition sync.h:1640
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,...
Definition sync.h:1651
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.
Definition sync.h:1619
Internal part of fsl_sc, uplifted into its own struct to simplify proper intialization of them in dow...
Definition sync.h:40
void * state
Available in callback() implementations via ch->debug.state.
Definition sync.h:80
fsl_buffer b
This is a scratch buffer solely for internal use by:
Definition sync.h:95
fsl_xfer_dbg_f callback
This optional method is intended to be set by client-level code, not the sync channel implementor.
Definition sync.h:72
Metrics for use with the library's "xfer" (sync) subsystem.
Definition sync.h:1340
fsl_size_t largestDecompressedResponse
Buffer capacity allocated for the latest single fossil-compressed response.
Definition sync.h:1371
fsl_size_t sentCards
Total sent cards.
Definition sync.h:1364
fsl_size_t cardsRx[fsl_xfcard_e_COUNT]
Counts of each card type seen in the response(s).
Definition sync.h:1384
fsl_size_t deltaRcvd
Number of deltas received.
Definition sync.h:1356
fsl_timer uncompress
Time taken to decompress cfile card payloads.
Definition sync.h:1404
fsl_timer read
Time spent waiting on fsl_sc::read(), but only via fsl__xfer_read(), fsl__xfer_readln(),...
Definition sync.h:1398
fsl_size_t deltaSent
Number of deltas sent.
Definition sync.h:1352
fsl_size_t fileRcvd
Number of files received.
Definition sync.h:1354
fsl_size_t largestCardPayload
Largest card payload size.
Definition sync.h:1366
fsl_size_t bytesWritten
Number of bytes via fsl__xfer_append() and friends.
Definition sync.h:1382
fsl_size_t cardsTx[fsl_xfcard_e_COUNT]
Counts of each card type sent in request(s).
Definition sync.h:1391
fsl_size_t danglingFile
Number of dangling deltas received.
Definition sync.h:1358
fsl_size_t privIGot
Number of private "igot" cards.
Definition sync.h:1346
fsl_timer submit
Time spent waiting on fsl_sc::submit().
Definition sync.h:1400
fsl_size_t rcvdCards
Total received cards.
Definition sync.h:1362
fsl_size_t rcvdArtifacts
Total received artifacts.
Definition sync.h:1360
fsl_timer process
Time taken to decompress cfile card payloads.
Definition sync.h:1408
fsl_size_t fileSent
Number of files sent.
Definition sync.h:1350
fsl_size_t iGotSent
Number of "igot" cards sent.
Definition sync.h:1344
fsl_size_t gimmeSent
Number of gimme cards sent.
Definition sync.h:1348
fsl_size_t trips
Number of connections made to the remote.
Definition sync.h:1342
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().
Definition sync.h:1380
fsl_size_t bytesReadCompressed
Number of compressed response bytes via fsl__xfer_submit().
Definition sync.h:1377
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.
Definition sync.h:34
#define fsl_xfcard_map(E)
Definition sync.h:1306
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.
fsl_sc_tracer_e
Definition sync.h:1240
@ FSL_SC_TRACER_default
Definition sync.h:1250
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.
Definition sync.h:1234
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...
Definition sync.h:1522
fsl_sc_F_lib_e
Flags for use with fsl_sc::flags.
Definition sync.h:119
@ FSL_SC_F_lib_mask
The mask of FSL_SC_F_... bits which are reserved for use by library-level options.
Definition sync.h:197
@ FSL_SC_F_COMPRESSED
Tells the fsl_sc impl that it should post data using the HTTP Content-Type value of "application/x-fo...
Definition sync.h:162
@ FSL_SC_F_REQUEST_HEADERS
For impls with this flag set, the library will populate their fsl_sc::requestHeaders immediately befo...
Definition sync.h:172
@ FSL_SC_F_client_mask
The mask of FSL_SC_F_... bits which are reserved for use by client-level options.
Definition sync.h:202
@ FSL_SC_F_SUPPRESS_STDERR
Impls which might, due to shelling out, emit info to stderr are expected to honor this flag and redir...
Definition sync.h:191
@ 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...
Definition sync.h:184
fsl_sc_init_e
Initialization modes for use with fsl_sc::init() implementations.
Definition sync.h:224
@ FSL_SC_INIT_REQUEST
Indicates that the object must (re)initialize any state needed for constructing a request.
Definition sync.h:245
@ FSL_SC_INIT_INITIAL
Indicates that the fsl_sc instance should initialize any core resources but not any request/response ...
Definition sync.h:231
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...
Definition sync.h:831
@ fsl_sc_popen_e_direct
Does not work!
Definition sync.h:874
@ fsl_sc_popen_e_default
Mode used by fsl_sc_popen_state_empty.
Definition sync.h:893
@ fsl_sc_popen_e_fd
Does not work!
Definition sync.h:888
@ fsl_sc_popen_e_membuf
Don't use this except for experimentation.
Definition sync.h:860
@ fsl_sc_popen_e_filebuf
Directs the binary's stdout to a temp file bound to fsl_sc_popen_state::response::fp using fopen().
Definition sync.h:845
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.
Definition sync.h:1458
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.
Definition sync.h:706
@ FSL_CFG_SYNC_XFER
Definition sync.h:715
@ FSL_CFG_SYNC_SKIN
Definition sync.h:709
@ FSL_CFG_SYNC_IWIKI
Definition sync.h:718
@ FSL_CFG_SYNC_OVERWRITE
Definition sync.h:720
@ FSL_CFG_SYNC_ALL
Definition sync.h:719
@ FSL_CFG_SYNC_ALIAS
Definition sync.h:716
@ FSL_CFG_SYNC_CSS
Definition sync.h:708
@ FSL_CFG_SYNC_PROJ
Definition sync.h:711
@ FSL_CFG_SYNC_TKT
Definition sync.h:710
@ FSL_CFG_SYNC_ADDR
Definition sync.h:714
@ FSL_CFG_SYNC_SUBSCRIBER
Definition sync.h:717
@ FSL_CFG_SYNC_NONE
Definition sync.h:707
@ FSL_CFG_SYNC_USER
Definition sync.h:713
@ FSL_CFG_SYNC_SHUN
Definition sync.h:712
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_xfcard_e
Definition sync.h:1317
@ fsl_xfcard_e_unknown
Definition sync.h:1320
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.