SDK: Backend

Die Methoden liegen auf app.backend (siehe App und Verbindung); Routen und Header stehen unter Backends. Diese Seite enthält den Status des Backends, seine Tokens und Tickets und den Backend-Abschnitt des Manifests.

Beim Build aus den TSDoc-Kommentaren von @pithyx/sdk 1.0.0-rc.9 erzeugt; der Text unter den Überschriften ist der Kommentar im Quelltext und bleibt Englisch.

Schnittstellen

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.

Eigenschaften

compose

compose: string;

Path of the Compose file inside backend/ of the package, usually backend/compose.yaml.

endpoints

endpoints: object;

The ports the proxy offers, by name. api is required: it is the default endpoint of app.backend.

Indexsignatur

[k: string]: BackendEndpoint

api

api: BackendEndpoint;

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?

optional idleTimeout?: number;

Seconds an onDemand backend keeps running after its last window closed. Default 600. Ignored for always.

root?

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?

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

services: string[];

The services of the Compose file that may connect out, for example only the one that fetches.

Min Items

1

Max Items

32

health?

optional health?: BackendHealth;

schedules?

optional schedules?: BackendSchedule[];

Recurring jobs that call the backend on a cron schedule, also without an open window.

Max Items

16

elevated?

optional elevated?: ElevatedPermission[];

Rights beyond the sandbox. The Compose file must use exactly what these allow.

Max Items

32

---

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}$”.

Eigenschaften

service

service: string;

port

port: number;

The port the service listens on inside the app’s internal network. It never gets a host port.

---

BackendHealth

The daemon calls GET path on endpoint to learn whether the backend is ready; a 2xx answer means running.

Eigenschaften

endpoint

endpoint: string;

A key of endpoints.

path

path: string;

---

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.

Eigenschaften

id

id: string;

Stable name, unique within the app; the Log Center names it with each run.

cron

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

endpoint: string;

A key of endpoints.

path

path: string;

---

BackendInfo

The app’s backend, as the window sees it.

Eigenschaften

status

status: BackendStatus;

Whether the backend runs; backendStatus follows it.

reason?

optional reason?: BackendUnavailableReason;

Why the backend cannot start, only while it is unavailable for that reason; backendStatus follows it.

endpoints

endpoints: string[];

The names of the endpoints the manifest declares under backend.endpoints; api is the default one.

---

BackendToken

A token for the app’s backend.

Eigenschaften

token

token: string;

The token, 256 bits; never log it.

expiresAt

expiresAt: string;

ISO 8601 UTC; ask again before then.

---

BackendTicket

A one-time ticket for one WebSocket connection to the app’s backend, valid 30 seconds.

Eigenschaften

ticket

ticket: string;

The ticket, for ?pithyx-ticket=.

expiresAt

expiresAt: string;

ISO 8601 UTC.

Typenaliasse

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

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).