Incant.Service behaviour (Incant v0.1.1)

Behaviour for service-owned Incant admin surfaces.

use Incant.Admin, rpc: true implements this behaviour and exposes it through SafeRPC. Application modules should usually use the Incant admin DSL instead of implementing this behaviour by hand.

Central Incant admin applications can discover Incant service modules from a HostKit/SafeRPC binding term, then use %Incant.Service.Client{} handles to call the standard Incant service verbs without repeating SafeRPC operation tuples at every call site.

Summary

Callbacks

describe(context)

index(surface_id, params, context)

read(surface_id, id, context)

run_action(surface_id, action_id, payload, context)

run_widget(surface_id, widget_id, variables, context)

Functions

client(binding_or_endpoint, opts)

Builds a client handle for a discovered Incant service module.

describe(client, request \\ %Describe{}, opts \\ [])

Calls the remote Incant service describe verb.

discover(bindings, opts \\ [])

Discovers Incant service clients from HostKit/SafeRPC local bindings.

index(client, request, opts \\ [])

Calls the remote Incant service index verb.

read(client, request, opts \\ [])

Calls the remote Incant service read verb.

run_action(client, request, opts \\ [])

Calls the remote Incant service run_action verb.

run_widget(client, request, opts \\ [])

Calls the remote Incant service run_widget verb.

Callbacks

describe(context)

@callback describe(context :: map()) ::
  {:ok, Incant.Admin.Contract.t()} | {:error, term()}

index(surface_id, params, context)

@callback index(surface_id :: String.t(), params :: map(), context :: map()) ::
  {:ok, map()} | {:error, term()}

read(surface_id, id, context)

@callback read(surface_id :: String.t(), id :: term(), context :: map()) ::
  {:ok, term()} | {:error, term()}

run_action(surface_id, action_id, payload, context)

@callback run_action(
  surface_id :: String.t(),
  action_id :: String.t(),
  payload :: map(),
  context :: map()
) :: {:ok, Incant.ActionResult.t()} | {:error, term()}

run_widget(surface_id, widget_id, variables, context)

@callback run_widget(
  surface_id :: String.t(),
  widget_id :: String.t(),
  variables :: map(),
  context :: map()
) :: {:ok, term()} | {:error, term()}

Functions

client(binding_or_endpoint, opts)

@spec client(SafeRPC.local_binding() | Incant.Service.Client.endpoint(), [
  {:module, module()}
]) ::
  Incant.Service.Client.t()

Builds a client handle for a discovered Incant service module.

The first argument may be a HostKit/SafeRPC local binding map containing a :socket key, or an already-started SafeRPC client process/name. Pass the service module with :module.

describe(client, request \\ %Describe{}, opts \\ [])

@spec describe(Incant.Service.Client.t(), Incant.Service.Describe.t(), keyword()) ::
  {:ok, term()} | {:error, term()}

Calls the remote Incant service describe verb.

discover(bindings, opts \\ [])

@spec discover(
  SafeRPC.local_bindings() | [SafeRPC.local_binding()],
  keyword()
) :: {:ok, [Incant.Service.Client.t()]} | {:error, term()}

Discovers Incant service clients from HostKit/SafeRPC local bindings.

Each HostKit binding provides trusted local candidate modules. Incant probes those candidates by calling the standard describe operation and returns the modules that answer with an Incant admin contract.

index(client, request, opts \\ [])

@spec index(Incant.Service.Client.t(), Incant.Service.Index.t(), keyword()) ::
  {:ok, map()} | {:error, term()}

Calls the remote Incant service index verb.

read(client, request, opts \\ [])

@spec read(Incant.Service.Client.t(), Incant.Service.Read.t(), keyword()) ::
  {:ok, term()} | {:error, term()}

Calls the remote Incant service read verb.

run_action(client, request, opts \\ [])

@spec run_action(Incant.Service.Client.t(), Incant.Service.RunAction.t(), keyword()) ::
  {:ok, Incant.ActionResult.t()} | {:error, term()}

Calls the remote Incant service run_action verb.

run_widget(client, request, opts \\ [])

@spec run_widget(Incant.Service.Client.t(), Incant.Service.RunWidget.t(), keyword()) ::
  {:ok, term()} | {:error, term()}

Calls the remote Incant service run_widget verb.