mirror of
https://github.com/Quad4-Software/Reticulum-Go
synced 2026-08-29 23:48:44 -04:00
59 lines
3 KiB
Go
59 lines
3 KiB
Go
// SPDX-License-Identifier: Apache-2.0
|
|
// Copyright (c) 2024-2026 Quad4.io
|
|
|
|
// Package controlapi implements a localhost-only JSON control plane for a
|
|
// running Reticulum-Go node. It lets applications written in any language
|
|
// use destinations, announces, links, request/response, identify, and
|
|
// minimal link resources without embedding the Go transport stack.
|
|
//
|
|
// # Wire protocol
|
|
//
|
|
// All routes are versioned under /v1 and require a bearer token equal to the
|
|
// node's hex-encoded rpc_key:
|
|
//
|
|
// Authorization: Bearer <hex rpc_key>
|
|
//
|
|
// HTTP routes:
|
|
//
|
|
// GET /v1/health node status
|
|
// GET /v1/status interface stats
|
|
// GET /v1/paths path table
|
|
// POST /v1/sessions create a session (identity)
|
|
// DELETE /v1/sessions/{id} tear down a session
|
|
// POST /v1/sessions/{id}/destinations register a destination
|
|
// POST /v1/sessions/{id}/destinations/{hash}/announce send an announce
|
|
// POST /v1/sessions/{id}/destinations/{hash}/requests bridge a request path to the WebSocket
|
|
// DELETE /v1/sessions/{id}/destinations/{hash}/requests deregister a request path (?path=)
|
|
// POST /v1/sessions/{id}/path/request request a path (returns wait_s)
|
|
// GET /v1/sessions/{id}/events WebSocket event stream
|
|
//
|
|
// A session owns one identity, the destinations registered under it, and
|
|
// the links it has opened or accepted. Binary values (hashes, app data,
|
|
// link payloads) are hex- or base64-encoded as noted on each
|
|
// request/response type in protocol.go.
|
|
//
|
|
// # Events and commands
|
|
//
|
|
// The events WebSocket pushes announce, link.established, link.failed,
|
|
// link.data, link.closed, link.remote_identified, request.incoming,
|
|
// request.response, request.failed, resource.started, resource.concluded,
|
|
// and command.error. It accepts subscribe_announces, link.open, link.send,
|
|
// link.close, link.request, link.send_resource, link.identify, and
|
|
// request.respond (optional filename for NomadNet file replies).
|
|
//
|
|
// subscribe_announces.filter must be empty (all announces) or an exact
|
|
// 16-byte destination hash as hex.
|
|
//
|
|
// # Scope
|
|
//
|
|
// The server binds to 127.0.0.1 by default and is disabled unless
|
|
// enable_control_api is set in the node configuration. It is an application
|
|
// contract over the transport, not a mirror of channels, buffers, or
|
|
// mesh-admin RPC. Large resources over base64 WebSocket frames are
|
|
// impractical. Prefer rncp or in-process librns for bulk transfers.
|
|
//
|
|
// Do not treat this API as a required remote control plane for a product.
|
|
// It fronts one local node. Application traffic should use destinations and
|
|
// links between peers. See docs/en/control-api.md (Architecture notes) and
|
|
// reticulum.network/manual/zen.html for upstream design intent.
|
|
package controlapi
|