Opsmaru.Incus.Operations.Host behaviour (opsmaru_incus v0.1.0)

Copy Markdown View Source

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

For an authenticated caller (a host-owned term, such as the host's MCP request context), the host returns the trusted backend and authorizes each operation with its validated input. Tool input never selects a socket, URL, credential, owner or host path; the operation selects a native project from input only after authorize/3 returns :ok.

A callback that is missing, raises, exits or returns anything else denies the call before any backend request. Calls run in the caller's process.

Summary

Types

caller()
operation()

Callbacks

allow_restricted?(caller, operation, items)

Allow restricted create/update input: each item is {:config, key} or {:device, name}. Without this callback restricted input is denied.

authorize(caller, operation, input)

Authorize the operation and its validated, normalized input (including project).

binding(caller, operation)

The backend for this caller and operation: a discovered client, or a connection and context the operation discovers with Opsmaru.Incus.connect/2 after authorization. The connection's timeout bounds every native request, including bounded waits.

image_remote(caller, name)

Resolve a host-approved image remote named in create input to its native source server and protocol. Without this callback only local images are used.

Types

caller()

@type caller() :: term()

operation()

@type operation() :: String.t()

Callbacks

allow_restricted?(caller, operation, items)

(optional) 
@callback allow_restricted?(
  caller(),
  operation(),
  items :: [{:config | :device, String.t()}]
) :: boolean()

Allow restricted create/update input: each item is {:config, key} or {:device, name}. Without this callback restricted input is denied.

authorize(caller, operation, input)

@callback authorize(caller(), operation(), input :: map()) :: :ok | {:error, term()}

Authorize the operation and its validated, normalized input (including project).

binding(caller, operation)

@callback binding(caller(), operation()) ::
  {:ok, Opsmaru.Incus.t()}
  | {:ok, Opsmaru.Incus.Connection.t(), Opsmaru.Incus.Context.t()}
  | {:error, term()}

The backend for this caller and operation: a discovered client, or a connection and context the operation discovers with Opsmaru.Incus.connect/2 after authorization. The connection's timeout bounds every native request, including bounded waits.

image_remote(caller, name)

(optional) 
@callback image_remote(caller(), name :: String.t()) ::
  {:ok, %{required(String.t()) => String.t()}} | {:error, term()}

Resolve a host-approved image remote named in create input to its native source server and protocol. Without this callback only local images are used.