API Reference opsmaru_incus v#0.1.0

Explicit native Incus client, independent of application startup and SQL.

Optional host-owned bounded concurrency, with no startup/recovery work.

Explicit immutable host-selected backend. Construction performs no I/O.

Pinned native API constant values, addressed by their original string names.

Trusted host binding for a direct library call. This is not authentication.

Native instance/snapshot/volume copy preparation over explicit bound clients. Returns accepted local or paired migration handles, never completed workloads. No address fallback, automatic relay activation, cancellation or data deletion.

Native connection/discovery helpers. Advertised addresses are metadata and are never followed.

Native dynamic console: one accepted operation/control channel and repeated explicit data attachments. Attachments, handshake time and total lifetime are bounded. The creating process owns the console; its exit or explicit close releases local channels, sending the pinned 1000 "Detaching from console" close frame on the control channel, without cancelling the backend operation. A failed attachment retains the operation and never repeats the console POST.

Native or local failure. :uncertain means a mutation may have been accepted. Inspect/log rendering excludes native message, response, credentials and URLs. Explicit fields retain backend data for caller reconciliation; never replay uncertain mutations automatically. Local failures do not cancel Incus work.

Explicit owner-bound event callbacks over one bounded native subscription. Callbacks run sequentially in isolated, monitored workers with a deadline; failure/overflow ends the local listener without cancelling backend work. wait/2 is repeatable and a local wait timeout leaves the listener active. No listener is created by loading the application or constructing a client.

Native bounded event subscription. Overflow requires authoritative reconciliation.

Pure bounded counterpart of native ParseFileHeaders. Header names are case-insensitive and the first duplicate wins, as with http.Header.Get. Native malformed numeric fields become -1; unknown type/write values remain caller data. Parsing does not authorize a file operation or contact a backend.

Native file/directory and backup handoff with host-owned bounded binary sources/sinks.

Immutable configuration for the optional native Incus gateway.

Host-started bounded admission for gateway exchanges.

Same-listener Cowboy dispatch for native SFTP/NBD upgrades.

A gateway-generated failure, encoded in the native Incus error shape.

Request/response header handling for the native relay.

Host policy contract for the native gateway.

Bounded public identity mediation. The host supplies explicitly verified backend metadata bound to the fixed connection. No discovery probe occurs. The conservative extension allowlist depends on the available optional protocol adapters. The host must approve only capabilities of protocols it actually mounts and of its verified backend. Migration extensions require WebSockets; token issuance remains excluded.

Exchange-local admission/revocation guard reusable by protocol adapters.

Mountable Plug relaying native Incus HTTP and optional WebSockets through host policy.

The single admission path shared by every gateway protocol adapter.

Normalized, bounded request metadata passed to host callbacks.

Native WebSocket adapter for a host-owned Plug.Cowboy listener.

Portable GetHTTPClient/DoHTTP slice over an explicitly bound native backend or verified image origin.

Bounded raw native HTTP response. Payload and origin are privileged caller values.

Accepted native handles of one image copy, returned by Images.copy/4.

Native create/rebuild from an image on explicit Incus clients. Remote pulls require the host to approve the exact verified HTTPS source origin. No advertised address fallback, mutation replay or automatic operation wait.

Native image transfers; host-owned sources/sinks and no mutation replay.

Reference declaration inventory. Changes are compared independently from implementation evidence; generated declarations never constitute parity.

Pure bounded native configuration-key lookup; does not apply configuration or contact Incus.

Native pull/push/relay negotiation between two explicit host-bound clients.

Typed native model value backed by pinned official JSON field schemas.

Pure native resource URL helpers; returns relative paths and never contacts advertised addresses.

Explicit pinned ConfigMap/DevicesMap JSON and YAML coercion, separate from lossless models.

Strict-subset YAML decoding for native ConfigMap/DevicesMap values.

Explicit native network Normalise helpers; ordinary Model.decode is lossless.

Portable pinned OCI image semantics through an explicit host-owned adapter.

Explicit host boundary for OCI inspection and conversion. No runner is bundled.

Native accepted operation bound to the originating backend and host identity. Poll/wait keep native identity and metadata. Local timeout/stream close never imply cancellation. Cancellation first checks authoritative may_cancel and issues at most one native DELETE. No application task/persistence is created.

Shared, protocol-neutral Incus operations for agents and direct callers.

One shared Incus operation: its public contract and how it runs.

Client evidence behind each operation, read from the ledgers at compile time.

Host binding for shared Incus operations. The host owns every trust decision.

Validates operation input against its own JSON Schema subset.

Explicit native ApplyServerPreseed orchestration; never invoked at startup.

Bounded pure native server-filter and event-log projections. Results are typed data for the host; this module never writes logs or authorizes disclosure. Filtering matches the pinned native suffix heuristic, not a general secret detector. Original lossless models remain unchanged.

Owner-monitored native SFTP/NBD duplex byte channel. No WebSocket framing.

Explicit local native-request lifetime, separate from host identity/readiness.

Native Incus envelope with lossless metadata/unknown fields and ETag.

SFTP v3 client over the native Incus raw upgrade, matching the pinned pkg/sftp v1.13.10 client returned by GetInstanceFileSFTP and GetStoragePoolVolumeFileSFTP. No SSH or host files.

An open SFTP file, matching the pinned pkg/sftp v1.13.10 *sftp.File as GetInstanceFileSFTP and GetStoragePoolVolumeFileSFTP configure it: 128 KiB packets, pipelined reads with up to 64 requests per file, and writes sent one at a time unless read_from_with_concurrency/3 is used.

Go path semantics used by the pinned pkg/sftp client: join/1, split/1, clean/1 and match/2. Paths are byte strings with / separators; nothing here touches a filesystem.

File attributes as the pinned pkg/sftp client returns them: its os.FileInfo name, signed size and Go os.FileMode (file_mode), plus the native FileStat fields. Attributes a reply omits are zero, as natively. Times are Unix seconds.

Filesystem statistics from the statvfs@openssh.com extension, as the pinned client decodes them.

Native server discovery; unknown/optional/null metadata remains in raw.

Byte-exact counterpart of the pinned ServerFiltered.MarshalYAML output as produced by go-yaml v4 yaml.Marshal (v3-compatible defaults: four-space indent, unlimited line width).

Native exec/console channels and controls, retaining accepted operation identity.

Explicit verified-HTTPS SimpleStreams catalog. Construction is passive; refresh/1 returns a new immutable connection-local catalog. The host supplies its native architecture explicitly, including any pinned platform fallback.

Explicit host-owned catalog cache, the counterpart of the pinned client's CachePath. Shared code never writes files.

Explicit host-owned delta conversion. No xdelta runner is bundled.

Pinned native operation/instance status names; unknown numeric codes stay native.

Pure immutable counterpart of the native shared/api.StatusError value.

Native Incus binary stream helpers for the official v7.0.1 typed methods

Pure native certificate/cluster token helpers. These format existing Incus operation metadata; they never create credentials, trust or runtime state. Encoded tokens and model data are privileged values and must not be logged.

Native HTTP binary transfers with bounded passive reads and acknowledged sinks.

Pure, immutable counterpart of the pinned API URL builder.

Bounded owner-monitored native WebSocket channel. Messages are pulled, never accumulated in the caller mailbox. Overflow, framing failures and deadlines are visible; local closure never implies backend cancellation.

Run mix opsmaru.incus.inventory --source .integration/incus-reference. The source checkout must be clean and at the exact pinned commit. --output selects an alternate inventory file for reproducibility/update comparisons. Requires the root mise Go toolchain; no Go code is part of the gateway.