class

Arcana::Server

Inherits Reference < Object

Network gateway — exposes the Bus and Directory over WebSocket + REST.

WebSocket clients connect, join with an address, and become full participants on the local Bus. Transparent bridging — local actors don't know whether they're talking to a local or remote agent.

REST endpoints expose the Directory for discovery and health checks.

bus = Arcana::Bus.new dir = Arcana::Directory.new server = Arcana::Server.new(bus, dir, port: 19118) server.start # blocking

Constructors

new(bus : Bus, directory : Directory, host : String = "0.0.0.0", port : Int32 = 19118)
Source

Instance methods

auth_required

When true, every REST request (except /health) and every WebSocket upgrade must present a valid Authorization: Bearer ak_... header that resolves via Arcana::Auth::ApiKey.verify. Requires the identity store (ARCANA_DATABASE_URL).

Source
auth_required=(auth_required : Bool)

When true, every REST request (except /health) and every WebSocket upgrade must present a valid Authorization: Bearer ak_... header that resolves via Arcana::Auth::ApiKey.verify. Requires the identity store (ARCANA_DATABASE_URL).

Source
events

Optional event recorder for auth failures and server lifecycle.

Source
events=(events : Events::Backend | Nil)

Optional event recorder for auth failures and server lifecycle.

Source
host
Source
load_tokens(tokens : Hash(String, String))

Bulk-replace tokens (used by snapshot restore).

Source
port
Source
start

Start the server. Blocks.

Source
start_in_background

Start in a background fiber.

Source
state_saver

Callback invoked after every state-changing REST op (/register, /unregister). The daemon wires this to Snapshot.save so state is persisted through the same path as graceful-shutdown saves — which respects the ephemeral flag and doesn't accumulate code-registered zombies across restarts.

Source
state_saver=(state_saver : Proc(Nil) | Nil)

Callback invoked after every state-changing REST op (/register, /unregister). The daemon wires this to Snapshot.save so state is persisted through the same path as graceful-shutdown saves — which respects the ephemeral flag and doesn't accumulate code-registered zombies across restarts.

Source
stop

Stop the server.

Source
tokens

TODO: Revisit token auth — currently a simple shared secret per address. Consider JWT, expiry, or key length requirements if Arcana is ever exposed beyond localhost.

Source