HostKit.Instance.Backend behaviour (host_kit v0.1.0-beta.5)

Copy Markdown View Source

Backend behaviour for lifecycle-managed HostKit instances.

A backend owns the compute boundary lifecycle for an HostKit.Instance. HostKit keeps the user DSL generic (instance, backend, image, kind, lifecycle, expose) and delegates backend-specific lifecycle operations to this behaviour.

Callback responsibilities:

  • read/2 inspects whether the declared instance exists and returns the observed instance or nil.
  • apply/2 makes the instance available for nested content application. For a VM/container backend this usually means create if missing, configure exposed ports, start, and wait until the instance can accept operations.
  • delete/2 destroys the instance when a down plan includes an ephemeral instance delete.

Backend options are stored on HostKit.Instance.backend_config by the DSL:

instance :demo do
  backend :incus, sudo: true, project: "hostkit"
end

Backends should emit %HostKit.Apply.Event{} progress through HostKit's apply event emitter when applying long-running lifecycle operations.

Summary

Callbacks

apply(t, keyword)
delete(t, keyword)
read(t, keyword)

Functions

apply(instance, opts)
delete(instance, opts)
module(backend)
read(instance, opts)

Callbacks

apply(t, keyword)

@callback apply(
  HostKit.Instance.t(),
  keyword()
) :: :ok | {:error, term()}

delete(t, keyword)

@callback delete(
  HostKit.Instance.t(),
  keyword()
) :: :ok | {:error, term()}

read(t, keyword)

@callback read(
  HostKit.Instance.t(),
  keyword()
) :: {:ok, HostKit.Instance.t() | nil} | {:error, term()}

Functions

apply(instance, opts)

@spec apply(
  HostKit.Instance.t(),
  keyword()
) :: :ok | {:error, term()}

delete(instance, opts)

@spec delete(
  HostKit.Instance.t(),
  keyword()
) :: :ok | {:error, term()}

module(backend)

@spec module(atom()) :: module()

read(instance, opts)

@spec read(
  HostKit.Instance.t(),
  keyword()
) :: {:ok, HostKit.Instance.t() | nil} | {:error, term()}