# Service admin interfaces Incant's distributed admin model is service-owned. Each service declares the admin surface it exposes in its own application namespace, using ordinary Incant DSL modules. A central Incant admin can discover, render, and dispatch those surfaces; it should not own the service's resource/action definitions. ```elixir defmodule Billing.Admin do use Incant.Admin, service: :billing, version: "1", repo: Billing.Repo expose Billing.Invoices.Invoice expose Billing.Customers.Customer dashboard Billing.Admin.Dashboards.Operations dataset Billing.Admin.Datasets.Revenue end ``` This mirrors how Mix tasks live in project namespaces: the framework defines the behaviour and conventions, while applications define their own modules. `expose/2` is convention-first. By default, Incant infers a resource from the Ecto schema and configured repo. If the application defines a conventional resource module, Incant uses it automatically without changing the admin root: ```elixir defmodule Billing.Admin.Resources.Invoice do use Incant.Resource, schema: Billing.Invoices.Invoice table do column :number, link: true column :status, as: :badge action :refund, confirm: true end end ``` Resolution order: 1. explicit `resource MyResourceModule` entries; 2. conventional override modules for `expose Schema`, such as `Billing.Admin.Resources.Invoice`; 3. inferred Ecto resources from `Schema.__schema__/1`. ## Local authoring, portable description Top-level admin concepts are normalized as surfaces. A surface is a common envelope around kind-specific metadata: ```elixir %Incant.Surface{ kind: :resource, id: "invoice", module: Billing.Admin.Resources.Invoice, title: "Invoices", spec: %Incant.Resource.Metadata{} } ``` The envelope owns identity for routes, navigation, public contracts, and remote transports. The `spec` owns resource/dashboard/dataset-specific semantics. The service-local module remains the source of truth: ```elixir Incant.metadata(Billing.Admin) Incant.Admin.describe(Billing.Admin) ``` `Incant.metadata/1` returns local BEAM metadata, which may include modules, function captures, repos, schemas, and callbacks. `Incant.Admin.describe/1` should return a portable, transport-safe admin contract. That contract is the thing suitable for remote discovery, persistence, audits, UI preloading, and SafeRPC responses. The important split is: - local metadata may contain executable BEAM terms; - public descriptions contain only stable data; - service-local executors own callbacks, repos, policies, and side effects. ## SafeRPC transport A service opts into SafeRPC by enabling RPC on its ordinary admin module: ```elixir defmodule Billing.Admin do use Incant.Admin, service: :billing, version: "1", repo: Billing.Repo, rpc: true expose Billing.Invoices.Invoice end ``` That module still implements the local `Incant.Service` behaviour: ```elixir Billing.Admin.describe(context) Billing.Admin.index("invoice", params, context) Billing.Admin.read("invoice", id, context) Billing.Admin.run_action("invoice", "refund", payload, context) ``` With `rpc: true`, those same service functions are exposed through SafeRPC as explicit module/function operations: ```elixir {Billing.Admin, :describe} {Billing.Admin, :index} {Billing.Admin, :read} {Billing.Admin, :run_action} ``` Central Incant admin code should not repeat those operation tuples directly. In a HostKit deployment it should load the runtime registry from the binding file path injected as `HOSTKIT_RPC_BINDINGS`: ```elixir {:ok, registry} = Incant.Service.Registry.load() for %Incant.Service.Entry{client: client, contract: contract} <- registry.entries do # render the contract and dispatch later user actions through the same client end ``` Long-running admin applications can supervise a registry server instead: ```elixir children = [ {Incant.Service.RegistryServer, name: MyApp.IncantRegistry} ] Supervisor.start_link(children, strategy: :one_for_one) entries = Incant.Service.RegistryServer.list_entries(MyApp.IncantRegistry) {:ok, registry} = Incant.Service.RegistryServer.refresh(MyApp.IncantRegistry) ``` A Phoenix app mounts local or service-backed Incant admin through the same router macro: ```elixir incant "/admin", MyApp.Admin incant "/admin", registry: MyApp.IncantRegistry ``` Incant can also run as a standalone app when configured with `serve?: true`: ```elixir config :incant, serve?: true, registry: [env: "HOSTKIT_RPC_BINDINGS"] ``` Standalone mode starts `Incant.Service.RegistryServer` and `Incant.Web.Endpoint`, then uses the same `incant` router macro internally. Library/embedded mode remains the default and starts no Incant children. Build the standalone release with: ```sh MIX_ENV=prod mix release incant ``` Runtime configuration uses standard Mix release config: ```text INCANT_SERVE=true INCANT_HTTP_IP=127.0.0.1 INCANT_HTTP_PORT=4000 INCANT_SECRET_KEY_BASE=... HOSTKIT_RPC_BINDINGS=/run/example/admin/rpc.etf ``` The macro owns the private Phoenix LiveView session shape. `Incant.Live.Admin` consumes a selected `Incant.Session` through the same protocol used for local admin modules; it does not branch on local vs remote transport. The registry decodes the ETF binding term safely: ```elixir bindings = path |> File.read!() |> :erlang.binary_to_term([:safe]) ``` Then it calls `SafeRPC.describe/1`, selects modules exposing the Incant service shape, and loads each contract through `Incant.Service.describe/1`. For lower-level callers, Incant can also discover service clients directly from decoded bindings: ```elixir {:ok, clients} = Incant.Service.discover(bindings) ``` For a known binding/module pair, callers can construct a client explicitly: ```elixir client = Incant.Service.client(binding, module: Billing.Admin) Incant.Service.index(client, %Incant.Service.Index{surface_id: "invoice", params: %{page: 1}}) Incant.Service.read(client, %Incant.Service.Read{surface_id: "invoice", id: "123"}) Incant.Service.run_action(client, %Incant.Service.RunAction{ surface_id: "invoice", action_id: "refund", payload: %{id: "123"} }) ``` UI code should usually wrap registry entries in `Incant.Service.Session` so rendering does not know about request structs: ```elixir session = Incant.Service.Session.new(entry, context: %{actor: actor}) Incant.Service.Session.list_surfaces(session, kind: :resource) Incant.Service.Session.index(session, "invoice", %{page: 1}) Incant.Service.Session.read(session, "invoice", "123") Incant.Service.Session.run_action(session, "invoice", "refund", %{id: "123"}) ``` SafeRPC moves request structs and responses. The service-local admin module still owns callbacks, repos, policies, and side effects. ## Standalone HTTP API Standalone Incant also exposes a JSON HTTP API for the same central-admin session boundary under `/incant`. The HTTP API is intentionally semantic: it resolves a discovered service entry, wraps it in `Incant.Service.Session`, and calls only the standard Incant session operations. It does not expose arbitrary module/function calls. Successful responses use the `application/vnd.incant.admin+json` media type and a typed document shape: ```json { "data": {}, "links": {}, "meta": {} } ``` Errors use RFC 9457 Problem Details with `application/problem+json`. Incant currently uses `type: "about:blank"` plus a stable `code` extension member until package docs define resolvable problem type URIs: ```json { "type": "about:blank", "code": "unknown-service", "title": "Unknown service", "status": 404, "detail": "No Incant service named billing is registered.", "instance": "/incant/services/billing" } ``` Routes: ```http GET /incant GET /incant/services GET /incant/services/:service GET /incant/services/:service/surfaces GET /incant/services/:service/surfaces/:surface GET /incant/services/:service/surfaces/:surface/rows POST /incant/services/:service/surfaces/:surface/queries GET /incant/services/:service/surfaces/:surface/rows/:id GET /incant/services/:service/surfaces/:surface/actions GET /incant/services/:service/surfaces/:surface/actions/:action POST /incant/services/:service/surfaces/:surface/actions/:action/runs ``` Request bodies use strict JSONCodec-backed contracts. JSON string keys are decoded once at the HTTP boundary into typed request structs such as `Incant.Web.API.QueryRequest` and `Incant.Web.API.ActionRunRequest`. Query request body: ```json { "table": {"page": 1, "page_size": 25}, "context": {} } ``` Action run request body: ```json { "payload": { "id": null, "selected_ids": null, "assigns": {}, "input": {} }, "context": {} } ``` Row actions set `payload.id`, bulk actions set `payload.selected_ids`, and page actions set neither. The service-local action callback still decides what the payload means and performs the side effect. Synchronous action runs return `200 OK` with an `action_run` resource in `data`; future asynchronous action runs should return `202 Accepted` with `Location` and `Retry-After`. Admin API responses include `Cache-Control: no-store` and `Vary: Accept`. Method mismatches return `405 Method Not Allowed` with an `Allow` header. Unsupported request media types return `415 Unsupported Media Type`; unacceptable `Accept` headers return `406 Not Acceptable`. ## Design constraints - Do not expose arbitrary remote MFA over the wire; only explicitly generated module/function operations are callable. - Do not serialize local callbacks or repo/schema modules as the public contract. - Keep action/resource identifiers stable and string-safe for URLs and RPC payloads. - Keep authorization service-local; the central UI can pass actor/context claims, but the service decides. - Treat the public description as inspectable data, not as executable code. - Keep semantic UI separate from transport. SafeRPC moves contracts and operation requests; Incant adapters render semantic surfaces. ## Direction The next Incant layer should introduce explicit modules for this boundary: - `Incant.Admin.describe/1` — local metadata to portable contract. - `Incant.Admin.Contract` — transport-safe admin contract struct/schema. - `Incant.Admin.Executor` — service-local resource/dataset/action execution. - `use Incant.Admin, rpc: true` — SafeRPC exposure for the admin module's standard service functions. - `Incant.Service.Client` — central-side client handle for remote admin surfaces.