Crate ledgence_worker_api 

Portable, vendor-independent worker contracts.

Program identity, immutable artifact preparation, reusable execution sessions, CloudEvents, monotonic deadlines, runtime requests, metrics and tracing form the adapter boundary. Implementations must retain process and artifact ownership until cleanup is confirmed. This crate supplies contracts, not a worker runtime, program store, process sandbox or durable orchestration service.

See the program package contract and worker delivery contract.

Modules

metrics

Closed-vocabulary operational observations, independent of any exporter SDK.

Structs

CloudEvent

Owns the original logical JSON event without rewriting user-owned data.

Digest

Error

ExecutionContext

ExecutionFailure

ExecutionReport

ExecutionRequest

InvocationIdentity

Correlation copied from the validated envelope, never from user-owned data.

NoopTraceBridge

Disabled tracing retains ordinary diagnostic spans and creates no trace IDs.

Platform

PreparedArtifact

Clones retain an opaque cache lease until the last runtime/consumer releases it.

ProgramDescriptor

ProgramManifest

ProgramRef

Names are filesystem-safe, lowercase, immutable release identifiers.

PythonRuntime

RunControl

Cancellation and a monotonic deadline; contains no runtime-specific types.

RuntimeExtension

Versioned, runtime-neutral context for an opt-in interactive invocation.

RuntimeInvocation

Ephemeral runtime input. The carrier belongs to the current execution span; it does not modify the durable request or its immutable CloudEvent.

RuntimeReply

An acknowledgement for exactly one request; its result schema belongs to the handler.

RuntimeRequest

One invocation-scoped request. The host, not these fields, supplies authority.

TraceContext

Origin and processing contexts have the same wire format but different lifetimes.

Enums

ErrorKind

Phase

ProgramOutcome

StartOutcome

Startup retains ownership whenever cleanup cannot be confirmed.

Constants

APPLICATION_INPUT_MAX_BYTES

Maximum compact JSON data bytes in the submission/delivery profile (1 MiB).

DEFAULT_RUNTIME_FRAME_MAX_BYTES

Default complete runtime frame budget, including its newline (2 MiB).

MAX_RUNTIME_VALUE_DEPTH

Envelope nesting allowance for opt-in interactive runtime payloads. Domain handlers must still validate each application value at the ordinary depth 64.

MAX_WIRE_VALUE_DEPTH

Maximum nested containers in a program result (a scalar has depth zero).

RUNTIME_EXTENSION_MAX_BYTES

Complete extension payload budget (640 KiB).

RUNTIME_REQUEST_MAX_BYTES

Interactive request/reply budget, including room around two 64 KiB values.

Traits

ArtifactCache

ArtifactLease

ExecutionRuntime

ExecutionSession

ProgramStore

Store futures must retain their underlying I/O until completion. Dropping a future is not proof that blocking or remote work stopped. The worker retains an admitted fetch after its response deadline until that future completes. Adapters must report completion only after their owned work has finished.

RuntimeRequestHandler

Invocation-scoped callback. Implementations bind authority outside the child payload. Dropping this future may leave a remote write uncertain; handlers must fence stale attempts and make repeated operations idempotent. A successful reply must acknowledge the requested operation before execution may continue.

TraceBridge

Connect existing instrumentation to a context provider without exposing its SDK. Set a parent and links before reading/materializing a span’s context. None explicitly starts a root, independently of any ambient transport span. Hooks must be nonblocking and nonpanicking; returned carriers must validate. Never perform export I/O here: allocation hooks may run inside a transaction.

Functions

decode_json

Decode JSON without silently rounding integer tokens outside i64/u64.

event_extensions

Helpers for constructing complete events in test/demo adapters; callers own IDs.

validate_cloudevent_context

Validate CloudEvents context attributes and W3C carriers independently of data. A concrete profile must separately constrain data presence, encoding, and size.

validate_json_cloudevent

Validate the shared JSON CloudEvents profile without requiring invocation IDs. Context and trace attributes retain their original representation; data is user-owned JSON. Callers separately enforce their payload size/depth limits.

validate_runtime_payload

Validate interactive envelope nesting and compact size without allocating the encoded payload. Ordinary application values use validate_wire_value.

validate_wire_value

Checks the structural limit shared by the Rust and Python result protocol.

Type Aliases

ExecutionResult

PortFuture

An adapter operation. Shared clients may be cloned/borrowed by their owner.

Result