SDK: backend
The methods are on app.backend (see app and connection); routes and headers are on Backends. This page has the backend’s status, its tokens and tickets, and the manifest’s backend section.
Generated from the TSDoc comments of @pithyx/sdk 1.0.0-rc.9 at build time; the text below the headings is the comment in the source.
Interfaces
Section titled “Interfaces”BackendManifest
Section titled “BackendManifest”An optional backend of one or more containers, described by a Compose file in the package and reached only through the daemon’s proxy.
Properties
Section titled “Properties”compose
Section titled “compose”compose: string;Path of the Compose file inside backend/ of the package, usually backend/compose.yaml.
endpoints
Section titled “endpoints”endpoints: object;The ports the proxy offers, by name. api is required: it is the default endpoint of app.backend.
Index Signature
Section titled “Index Signature”[k: string]: BackendEndpointapi: BackendEndpoint;lifecycle
Section titled “lifecycle”lifecycle: 'always' | 'onDemand';always: runs while the app is installed and its pool is available. onDemand: runs while at least one window of the app is open for any user, plus idleTimeout, or while a schedule holds it.
idleTimeout?
Section titled “idleTimeout?”optional idleTimeout?: number;Seconds an onDemand backend keeps running after its last window closed. Default 600. Ignored for always.
optional root?: boolean;The containers run as root inside the container (unprivileged on the host through user namespaces). The install dialog warns about it. Default false: they run as the app’s own user.
network?
Section titled “network?”optional network?: object;Which services get the network out of the box that network.internet and network.lan open. Without it every service gets it; the others stay on the app’s internal network only. No effect without one of the two permissions.
services
Section titled “services”services: string[];The services of the Compose file that may connect out, for example only the one that fetches.
Min Items
Section titled “Min Items”1
Max Items
Section titled “Max Items”32
health?
Section titled “health?”optional health?: BackendHealth;schedules?
Section titled “schedules?”optional schedules?: BackendSchedule[];Recurring jobs that call the backend on a cron schedule, also without an open window.
Max Items
Section titled “Max Items”16
elevated?
Section titled “elevated?”optional elevated?: ElevatedPermission[];Rights beyond the sandbox. The Compose file must use exactly what these allow.
Max Items
Section titled “Max Items”32
BackendEndpoint
Section titled “BackendEndpoint”A port of a backend service that the proxy offers to the app’s windows. Container ports never appear in a URL: the endpoint api is /apps/<id>/api/, every other endpoint <name> is /apps/<id>/api-<name>/.
This interface was referenced by undefined’s JSON-Schema definition
via the patternProperty “^[a-z][a-z0-9-]{0,31}$”.
Properties
Section titled “Properties”service
Section titled “service”service: string;port: number;The port the service listens on inside the app’s internal network. It never gets a host port.
BackendHealth
Section titled “BackendHealth”The daemon calls GET path on endpoint to learn whether the backend is ready; a 2xx answer means running.
Properties
Section titled “Properties”endpoint
Section titled “endpoint”endpoint: string;A key of endpoints.
path: string;BackendSchedule
Section titled “BackendSchedule”A recurring backend job. The daemon starts the backend for it even without an open window and calls POST path on endpoint when it fires.
Properties
Section titled “Properties”id: string;Stable name, unique within the app; the Log Center names it with each run.
cron: string;Five fields separated by single spaces (minute 0-59, hour 0-23, day of month 1-31, month 1-12, day of week 0-7 with 0 and 7 for Sunday), in the box’s time zone. Each field is a comma list of *, numbers and ranges a-b; * and ranges may take a step /n. No names.
endpoint
Section titled “endpoint”endpoint: string;A key of endpoints.
path: string;BackendInfo
Section titled “BackendInfo”The app’s backend, as the window sees it.
Properties
Section titled “Properties”status
Section titled “status”status: BackendStatus;Whether the backend runs; backendStatus follows it.
reason?
Section titled “reason?”optional reason?: BackendUnavailableReason;Why the backend cannot start, only while it is unavailable for that reason; backendStatus follows it.
endpoints
Section titled “endpoints”endpoints: string[];The names of the endpoints the manifest declares under backend.endpoints; api is the default one.
BackendToken
Section titled “BackendToken”A token for the app’s backend.
Properties
Section titled “Properties”token: string;The token, 256 bits; never log it.
expiresAt
Section titled “expiresAt”expiresAt: string;ISO 8601 UTC; ask again before then.
BackendTicket
Section titled “BackendTicket”A one-time ticket for one WebSocket connection to the app’s backend, valid 30 seconds.
Properties
Section titled “Properties”ticket
Section titled “ticket”ticket: string;The ticket, for ?pithyx-ticket=.
expiresAt
Section titled “expiresAt”expiresAt: string;ISO 8601 UTC.
Type Aliases
Section titled “Type Aliases”BackendStatus
Section titled “BackendStatus”type BackendStatus = 'stopped' | 'starting' | 'running' | 'updating' | 'unavailable';The state of the app’s backend: stopped (not running, for example an onDemand backend without windows),
starting, running, updating (a new version is being installed) or unavailable (it failed, or it cannot start
and reason says why). A request to a stopped or starting backend wakes it and waits until it runs (at most 30
seconds); while it is updating or unavailable the proxy answers 503 app.backend.unavailable.
BackendUnavailableReason
Section titled “BackendUnavailableReason”type BackendUnavailableReason = 'storage' | 'pool';Why an unavailable backend cannot start until an administrator acts: storage (a required storage request has no
folder yet; context.storage shows it as unmapped) or pool (the app pool is locked or missing).