Skip to content

Guided tour

FabrCore 2.0 · Release and package availability

These guides track the current 2.0 source. Stable 2.0.0 publication is pending; package commands show the release target. Until it is published, follow the source quick start or use a matching available prerelease set. Release migration · Runtime modes

MODULE 13 · LESSON 13.7

Implement outbound remote administration

Relay administration over an outbound long-poll connection.

Lesson 80 of 86 · FabrCore 2.0

Overview

Outbound v2 lets a Host behind a firewall receive privileged commands without exposing its administration port publicly. Reliability requires durable command identity, leases, expiry and duplicate handling. This transport is independent of user WebSocket chat.

Long polling crosses the firewall in the Host's direction

The Host initiates a bounded connect request to the Cloud Server. The response can carry a queued administration command; the Host dispatches it through its allowed local administration surface and posts the result back. User chat does not pass through this command queue. Authenticate the relay as a privileged cluster boundary.

Leases and receipts handle unreliable networks

A server must retain command identity, lease token, expiry and results across reconnects. A repeated response should reconcile the same command rather than create another operation. Expiring a waiting request does not undo an effect already executed at the Host. Preserve status codes, preconditions and response bodies so remote clients see the original operation semantics.

Implement the outbound relay

  1. Implement connect and response endpoints with cluster authentication, bounded long polls, correlation IDs and response-size limits.
  2. Persist command/operation records, issue leases and reconcile retries/duplicate responses. Honor cancellation and expiration without assuming an expired wait undoes a completed command.
  3. Dispatch only supported administration operations and preserve revisions and per-target results. Test reconnect, late responses and offline hosts.
Outbound remote administration channel (v2) · reference snippet 
{
  "commandId": "3f84f4fc-9cb8-4f68-a6ab-c8e41f840a6e",
  "method": "GET",
  "pathAndQuery": "/fabrcoreapi/capabilities",
  "headers": {
    "accept": ["application/json"],
    "x-user-handle": ["[email protected]"]
  },
  "body": null,
  "expiresAt": "2026-07-29T18:00:45Z"
}
Outbound remote administration channel (v2) · reference snippet 
{
  "commandId": "3f84f4fc-9cb8-4f68-a6ab-c8e41f840a6e",
  "statusCode": 200,
  "headers": {
    "content-type": ["application/json"]
  },
  "body": "eyJzZXJ2aWNlcyI6W119",
  "error": null
}

Interrupt a leased command deliberately

  1. Queue a harmless read command for the development Host and observe its connect delivery and correlated response. Confirm it targets the intended cluster/environment.
  2. Disconnect during a controlled operation and reconnect. Inspect the persisted command/lease/receipt rather than creating a replacement command automatically.
  3. Replay a duplicate or late response in a test. The server should reconcile it against the existing command and preserve the final outcome without duplicating business execution records.

The relay is correct when identity and outcome survive network uncertainty. It must not become an arbitrary public HTTP proxy into the Host.

If the result is different

Do not turn a relay into an arbitrary unauthenticated HTTP proxy. Treat indeterminate mutation outcomes as reconciliation work, not automatic replay permission.

Go deeper

Explore the related documentation.