functions.v1.FunctionsService, with messages in
protos/functions/v1/invocations.proto. See
Invocations for the lifecycle, and
HTTP endpoints for the same calls
over plain HTTP.
RPCs
Invoke
The input is checked against the version’s contract before anything runs and
the output after the function writes it. The call waits in the queue while
every host is busy or the function is at its
max_concurrency, until the
call’s deadline: Connect-Timeout-Ms when set, capped at
INVOKE_MAX_DEADLINE (default 1 hour), or INVOKE_DEADLINE (default 5
minutes).
An RPC error means the function produced no result. If the function ran, the
RPC succeeds and the response carries its output or a FunctionError.
FunctionError has a kind, a message, a function-supplied type (for
RAISED only) and violations (for OUTPUT_INVALID only).
StartKind is COLD_BOOT, SNAPSHOT_RESTORE or WARM.
Retries
An attempt that raised, crashed or timed out, or that the platform could not run, runs again up to the call’s or the function’sretries, while the
deadline leaves room. The wait starts at RETRY_BACKOFF (default 1s), grows
five times per attempt and stops growing at RETRY_BACKOFF_MAX (default 5m).
An input that violates the contract never runs again.
Idempotency
WithinIDEMPOTENCY_WINDOW (default 24h), a call to the same function with
the same key returns the invocation the first call started, with its output
or error, and replayed set. A call still in flight is waited on. The key is
released for a new run only when the platform never sent the invocation to a
host. A call a host took but never reported on holds the key, and a retry gets
aborted. Use a new key to run again.
Keys on Invoke need a logs bucket (LOGS_BUCKET) to keep outputs in, or
the call is failed_precondition.
Errors
A host can also refuse an invocation with
resource_exhausted,
invalid_argument, unavailable, not_found, failed_precondition or
aborted, which the server passes through.
InvokeAsync
Takes the same fields asInvoke. Returns once the invocation is queued, with
invocation_id and replayed. Nothing waits for it and its output is dropped.
Its status, attempts, error and logs are recorded. It retries as Invoke
does and may wait in the queue and between attempts for up to ASYNC_MAX_AGE
(default 24h), after which the host that takes it records it CANCELED.
An idempotency_key seen within the window returns the invocation that call
queued, with replayed set. Async keys do not need a logs bucket. Follow the
invocation with GetInvocation.
GetInvocation
Takesid. Returns the Invocation from the database, or from the server
holding it while it runs and until its record is written. An unknown id is
not_found.
ListInvocations
Results are newest first. An invocation appears once its record reaches the
database, after it ends or, for async invocations, once it is queued.
GetInvocationLogs
A server-streaming RPC that sends what the function wrote to stderr asdata chunks, in order. Chunks are not split on line boundaries.
An ended attempt is read from the logs bucket. A running one, or one whose
upload has not completed, is read from NATS, which keeps only recent lines for
LOGS_RETENTION (default 1h). An attempt below 0 or past the invocation’s
attempts is not_found. See Logs.
TailInvocations
A server-streaming RPC of lifecycle transitions across every server, until the client goes away.
Each
TailInvocationsResponse carries the invocation, an event_type (the
status as a lowercase token such as running or succeeded), replay and
emitted_at in epoch milliseconds. A slow client that falls 256 events behind
loses events rather than holding up invocations. Reconnect with
should_replay to catch up. If the servers cannot be asked for replay, the
call is unavailable.