Declaraciones públicas de media-core/source/local_file.zig (media-core: fuentes locales).
apps/docs/generated/zig/media-core-source.jsonPágina generada desde
native/zig/media-core/source/local_file.zig. No se edita a mano:bun run docs:genla regenera ybun run docs:checkfalla si difiere.
LocalFileSource — mirrors ISeekableMediaSource from @styx/source-sdk (r04).
Provides random-access reads from a local file using pread, with purposes
that mirror the TS contract: probe | playback | seek | trick_play | subtitle |
background_cache. Buffer ownership is explicit — the caller receives a freshly
allocated slice and is responsible for freeing it via the same allocator.
NO imports from TypeScript packages. This is a pure Zig implementation that
mirrors the interface contract defined in packages/source-sdk/src/source.ts.
backpressure_wakernamespace · línea 18
pub const backpressure_waker = @import("backpressure_waker")Sin ///.
BackpressureWakerconst · línea 19
pub const BackpressureWaker = backpressure_waker.BackpressureWakerSin ///.
BackpressureProfileconst · línea 20
pub const BackpressureProfile = backpressure_waker.BackpressureProfileSin ///.
engine_sourcenamespace · línea 26
pub const engine_source = @import("engine_source.zig")dec-0110 §1: LocalFileSource as the media engines' ByteSource.
transport_signalsnamespace · línea 28
pub const transport_signals = @import("transport_signals")Sin ///.
TransportSignalsconst · línea 29
pub const TransportSignals = transport_signals.TransportSignalsSin ///.
TransportSignalsChannelconst · línea 30
pub const TransportSignalsChannel = transport_signals.TransportSignalsChannelSin ///.
TransportSnapshotconst · línea 31
pub const TransportSnapshot = transport_signals.TransportSnapshotSin ///.
ReadPurposetype · línea 36
pub const ReadPurpose = enumPurpose of a read request — mirrors ReadPurpose from ISeekableMediaSource.
Affects scheduling priority in the scheduler (F0.B.2); in F0.B.1 the purpose
is accepted but does not change behaviour (no scheduler yet).
ReadPurpose.toStringfn · línea 44
pub fn toString(self: ReadPurpose) []const u8Sin ///.
ReadRequesttype · línea 57
pub const ReadRequest = structA read request — mirrors IReadRequest from ISeekableMediaSource.
ReadResulttype · línea 73
pub const ReadResult = structResult of a read — mirrors IReadResult from ISeekableMediaSource.
SourceErrorconst · línea 87
pub const SourceError = error{ unknown, file_not_found, permission_denied, io_error, cancelled, deadline_exceeded, invalid_offset, /// The path is outside the media root, crosses a symlink or `..`, or …Local source errors. The TS side (SourceErrorCode in @styx/source-sdk)
is generated from SourceErrorSpace (zig build gen:source-errors), and a
test fails when the committed file diverges.
SourceErrorSpaceconst · línea 107
pub const SourceErrorSpace = zkit.errors.ErrorSpaceWith(SourceError, &.{.{ .name = "local_file", .base = 1000, .entries = &.{ .{ .tag = "unknown", .message = "Error desconocido del source" }, .{ .tag = …Codes and TS names of SourceError. The order is the numeric ABI: append,
never reorder.
errorCodeNamefn · línea 131
pub fn errorCodeName(err: anyerror) []const u8Wire name of a failed source operation (SOURCE_*), or SOURCE_UNKNOWN
for an error outside SourceError (allocator failure).
DEFAULT_MAX_RANGE_LENGTH_BYTESconst · línea 142
pub const DEFAULT_MAX_RANGE_LENGTH_BYTES: u64 = 16 * 1024 * 1024TKT-009 G8: max range length, in bytes. Default 16 MiB (matches
ThreatModel-v0 §5). Overridable via STYX_MEDIA_MAX_RANGE_LENGTH (decimal
bytes). Read once on first validation (env var lookup is a syscall; we
cache the result in an atomic so per-read cost is one load).
Configured at module init via initMaxRangeLength(); tests can also
override directly via setMaxRangeLength().
getMaxRangeLengthfn · línea 148
pub fn getMaxRangeLength() u64Read the current max range length. Atomic load — safe to call from any thread.
setMaxRangeLengthfn · línea 156
pub fn setMaxRangeLength(v: u64) voidOverride the max range length at runtime. Used by tests + by main.zig
after parsing STYX_MEDIA_MAX_RANGE_LENGTH. Out-of-range or invalid
values are silently clamped to [1, 1 GiB] — the absolute upper bound
prevents a misconfiguration from killing the daemon.
initMaxRangeLengthfn · línea 165
pub fn initMaxRangeLength() voidRead STYX_MEDIA_MAX_RANGE_LENGTH from the environment and apply it.
Called once at startup from main.zig so the value is stable for the
rest of the daemon's lifetime. Unset: the default applies; malformed:
the default applies and it is logged.
AssetReftype · línea 176
pub const AssetRef = structWhere an asset lives (dec-0117 I7): a root the daemon opened at start-up, named by its id, and a path relative to it. The IPC carries exactly this; no absolute path reaches an open.
AssetRef.parsefn · línea 181
pub fn parse(text: []const u8) ?AssetRef<rootId>/<relPath> (operator config such as the dev MoQT fixture).
AssetRef.formatfn · línea 192
pub fn format(self: AssetRef, w: *std.Io.Writer) std.Io.Writer.Error!voidroot://<rootId>/<relPath> ({f}): the only shape a log line may print an asset in.
The OTLP sanitizer keeps the rootId and hides the relPath of exactly this form
(dec-0135 D5); tools/log_path_audit.zig fails a log call that prints a relPath
any other way.
max_rootsconst · línea 198
pub const max_roots = 16Most roots the daemon keeps; also the most STYX_MEDIA_ROOTS may list.
max_root_id_lenconst · línea 200
pub const max_root_id_len = 64Root ids: the same class as the ingest root id of the contracts.
validRootIdfn · línea 202
pub fn validRootId(id: []const u8) boolSin ///.
RootSpectype · línea 212
pub const RootSpec = structOne entry of the root table as the operator declares it.
RootsSpecErrorconst · línea 219
pub const RootsSpecError = error{ TooManyRoots, InvalidRootId, DuplicateRootId, EmptyPath, UnknownRootFlag }Sin ///.
parseRootsSpecfn · línea 225
pub fn parseRootsSpec(text: []const u8, out: *[max_roots]RootSpec) RootsSpecError![]RootSpecParses id=path[:ro][:trusted],id2=path2… (STYX_MEDIA_ROOTS). The
returned specs slice into text. ro is accepted and is what every
media root is anyway: the daemon never opens one for writing. A : whose
suffix contains a / stays part of the path.
SetRootsErrorconst · línea 287
pub const SetRootsError = zkit.safety.fs.Error || RootsSpecErrorSin ///.
setMediaRootsfn · línea 293
pub fn setMediaRoots(specs: []const RootSpec) SetRootsError!voidReplaces the whole root table (daemon start-up, tests), all or nothing: if one root cannot be opened, the previous table stays. A root path is the operator's directory; it may itself be a symlink, what is below it may not.
setMediaRootfn · línea 314
pub fn setMediaRoot(root_id: []const u8, path: []const u8) SetRootsError!voidA table of one root (tests, the CLI).
clearMediaRootsfn · línea 319
pub fn clearMediaRoots() voidNo roots: every open fails with path_traversal.
rootCountfn · línea 325
pub fn rootCount() usizeSin ///.
initMediaRootsfn · línea 334
pub fn initMediaRoots() voidOpens every root of STYX_MEDIA_ROOTS. Unset, empty, malformed or with
a root that cannot be opened ⇒ no roots at all (fail-closed): the
operator gets the whole table or nothing, never a partial one.
LocalFileSourcetype · línea 383
pub const LocalFileSource = structA LocalFileSource provides random-access reads from a file on disk. Implements the ISeekableMediaSource contract in pure Zig (no TS imports).
All reads use pread for true random access without seeking the file pointer.
Buffer ownership is explicit: readAt allocates the return buffer using the
provided allocator; the caller must free it.
Thread-safety: not required in F0.B.1 (single-threaded daemon). The scheduler in F0.B.2 will serialise accesses per source.
LocalFileSource.openfn · línea 404
pub fn open(allocator: std.mem.Allocator, uri: []const u8, ref: AssetRef) SourceError!LocalFileSourceOpens ref for reading beneath its root (setMediaRoots /
initMediaRoots). uri is stored as-is (not owned).
LocalFileSource.closefn · línea 427
pub fn close(self: *LocalFileSource) voidClose the source and release all resources.
The uri slice is NOT freed (caller owns it).
LocalFileSource.getSizefn · línea 434
pub fn getSize(self: *const LocalFileSource) u64Return the total size in bytes. May be 0 if the size cannot be determined.
LocalFileSource.readAtfn · línea 454
pub fn readAt(self: *LocalFileSource, request: ReadRequest) !ReadResultRead request.length bytes starting at request.offset using pread.
Buffer ownership: a freshly allocated []u8 is returned in
ReadResult.data. The caller owns this buffer and must free it using
allocator.free(result.data).
EOF behaviour: if offset >= size_bytes, returns ReadResult with
eof=true and data.len=0. If pread returns fewer bytes than
requested, eof=true is set in the result.
Cancellation (F0.B.1): request.request_id is accepted for
compatibility with the IPC contract but has no effect (no active
canceller in F0.B.1). The F0.B.2 scheduler will use it.
deadline_at (F0.B.1): accepted but not enforced. F0.B.2 scheduler will check and reject expired reads.
LocalFileSource.readIntofn · línea 537
pub fn readInto(self: *LocalFileSource, offset: u64, dst: []u8, purpose: ReadPurpose) SourceError!usizePositional read into a caller-owned buffer, no allocation: the door
the media engines read through (engine_source.EngineSource,
dec-0110 §1). Same range cap as readAt. Returns the bytes copied
(fewer than dst.len only at EOF).
generated_ts_headerconst · línea 797
pub const generated_ts_header = \\// GENERATED by `zig build gen:source-errors` from SourceErrorSpace \\// (native/zig/media-core/source/local_file.zig). Do not edit. \\ \\First lines of the generated TS file (zig build gen:source-errors).