Declaraciones públicas de zig/client.zig (conduit-zig (SDK consumido)).
apps/docs/generated/zig/conduit.jsonPágina generada desde
conduit@conduit-0.1.0-f7J_7zg5DwCsHBHItwdOz9ZVq8cvH7ceFsk7-m3-T61t (zig/root.zig). No se edita a mano:bun run docs:genla regenera ybun run docs:checkfalla si difiere.
The upload state machine (spec §6), sans-IO.
The machine never touches a file or a socket. The host loops:
while (true) switch (up.poll()) { .control => |c| { send up.controlRequest(c, &buf); up.onControlResponse(status, body) }, .read => |r| { bytes = read(file, r.offset, r.len); const t = try up.onChunkData(r.index, bytes); if (t.send) { POST t.request; up.onChunkResponse(r.index, status, body) } }, .wait => wait for an outstanding request, .done, .failed => break, }
so the same machine drives the Zig CLI (threads + std.http), Swift
(URLSession, via the C-ABI), Bun (FFI) and the web (WASM). All decisions
— chunk plan, window, retries, resume reconciliation, hashing — live here
once; the wire codec is wire.zig.
Hashing is streaming and every byte is hashed once per read.
onChunkData must be called for fresh chunks in index order
(the order poll hands them out); the file SHA-256 is fed there, the
chunk SHA-256 goes into Content-Digest (two SHA-256 per byte: the
wire's cost).Options.protocol = .v2, spec/wire-v2.md): each chunk is a
power-of-two subtree of the file's BLAKE3 tree; its chaining value
goes into Conduit-Chunk-Cv and the root (b3sum of the file) is the
combination of the CVs — one BLAKE3 pass per byte, chunks in any
order. Negotiated: a server that does not answer "protocol":2
speaks v1 and the machine continues in v1 (nothing was hashed yet).A re-read (retry) whose digest differs from the first read fails the
upload with source_changed instead of sending different bytes under the
same index.
client.Modetype · línea 43
pub const Mode = enumSin ///.
client.Protocoltype · línea 51
pub const Protocol = enumSin ///.
client.Optionstype · línea 53
pub const Options = structSin ///.
client.Purposetype · línea 81
pub const Purpose = enumSin ///.
client.ChunkReftype · línea 90
pub const ChunkRef = structSin ///.
client.ControlKindtype · línea 100
pub const ControlKind = enumSin ///.
client.Actiontype · línea 102
pub const Action = unionSin ///.
client.FailureKindtype · línea 110
pub const FailureKind = enumSin ///.
client.Failuretype · línea 127
pub const Failure = structSin ///.
client.Requesttype · línea 134
pub const Request = structSin ///.
client.RequestBuftype · línea 151
pub const RequestBuf = structStorage for a Request (paths, headers, JSON). Owned by the host, so the
request stays valid while the host sends it — even across threads.
client.Tickettype · línea 160
pub const Ticket = structSin ///.
client.Progresstype · línea 171
pub const Progress = structSin ///.
client.EventErrorconst · línea 178
pub const EventError = error{ /// The host called an event that does not match the machine's state /// (wrong index, wrong length, no such outstanding request). InvalidEvent, /// A fresh chunk was del …Sin ///.
client.Uploadtype · línea 190
pub const Upload = structSin ///.
client.Upload.InitErrorconst · línea 238
pub const InitError = wire.PlanError || wire.ParseError || Allocator.Error || error{InvalidOptions}Sin ///.
client.Upload.initfn · línea 242
pub fn init(gpa: Allocator, opts: Options, resume_id: ?wire.UploadId) InitError!Uploadresume_id: the uploadId of an earlier run (persisted by the host).
The machine probes it first and falls back to a new session on 404.
client.Upload.deinitfn · línea 288
pub fn deinit(self: *Upload) voidSin ///.
client.Upload.uploadIdfn · línea 302
pub fn uploadId(self: *const Upload) ?wire.UploadIdSin ///.
client.Upload.failureInfofn · línea 306
pub fn failureInfo(self: *const Upload) ?FailureSin ///.
client.Upload.sha256fn · línea 311
pub fn sha256(self: *const Upload) ?wire.DigestSHA-256 of the uploaded file, when it finished in wire v1.
client.Upload.rootfn · línea 316
pub fn root(self: *const Upload) ?tree.CvBLAKE3 root of the uploaded file (b3sum), when it finished in wire v2.
client.Upload.protocolfn · línea 322
pub fn protocol(self: *const Upload) ProtocolThe wire the session speaks (final once the server answered create or the resume probe).
client.Upload.setConcurrencyfn · línea 345
pub fn setConcurrency(self: *Upload, n: u16) voidChunks the host may have being read or sent from now on, clamped to
[1, opts.concurrency]. Lowering it does not cancel what is in
flight; poll just hands out fewer until it is under the new limit.
client.Upload.refuseEncodingsfn · línea 352
pub fn refuseEncodings(self: *Upload) voidStop offering content-codings (the host's policy found the payload not worth encoding: media, already compressed, or it does not shrink). Valid before the create request is sent.
client.Upload.finalPathfn · línea 358
pub fn finalPath(self: *const Upload) ?[]const u8Server key of the finished file (finalPath), valid until deinit.
client.Upload.progressfn · línea 362
pub fn progress(self: *const Upload) ProgressSin ///.
client.Upload.pollfn · línea 376
pub fn poll(self: *Upload) ActionSin ///.
client.Upload.onChunkDatafn · línea 497
pub fn onChunkData(self: *Upload, index: u32, bytes: []const u8, buf: *RequestBuf) EventError!TicketThe host read chunk index (the bytes of poll's .read). Returns
the request to send when ticket.send; buf must outlive the send.
client.Upload.onChunkHashedfn · línea 529
pub fn onChunkHashed(self: *Upload, index: u32, len: u64, node: tree.Node, buf: *RequestBuf) EventError!Ticketwire v2, for hosts that hash outside their lock (the driver's
workers do, so chunks hash on every core): the chunk's node from
chunkNode, computed on the bytes of poll's .read. Same effect
as onChunkData with those bytes.
client.Upload.chunkNodefn · línea 552
pub fn chunkNode(plan: wire.Plan, index: u32, bytes: []const u8) tree.NodeThe node of chunk index in the file's BLAKE3 tree (wire v2): one
pass over its bytes as a subtree at its offset (an aligned power of
two, so its CV is a node of the file's tree). Pure; any thread.
client.Upload.onChunkResponsefn · línea 607
pub fn onChunkResponse(self: *Upload, index: u32, status: u16, body: []const u8) EventError!voidResponse to a chunk POST (status 0 = transport error: no response).
client.Upload.controlRequestfn · línea 656
pub fn controlRequest(self: *Upload, kind: ControlKind, buf: *RequestBuf) RequestSin ///.
client.Upload.onControlResponsefn · línea 693
pub fn onControlResponse(self: *Upload, status: u16, body: []const u8) EventError!voidResponse to the outstanding control request (status 0 = transport
error).