jschoubben
9c9d03691b
The go.mod comment and the contract package's comment still described a separate Go module with its own tags. Issue 1126. Claude-Session: https://claude.ai/code/session_01NcbgfJ9Gum47zkFKWRaovL
77 lines
3.9 KiB
Go
77 lines
3.9 KiB
Go
// Package contract is route-proxy's contract for the provision `route`: what a consumer asks a route with, what the
|
|
// proxy keeps on the bus about what it serves, the events it says, and its tools' arguments (issue 774; research 072
|
|
// row 34; the operator, 2026-10-31: "the route-proxy should define its own contract for the seat (with the message
|
|
// contracts of course) which other modules can use").
|
|
//
|
|
// **A package of the route-proxy module**, imported as `route-proxy/contract`: standard library only, built from the
|
|
// same tree as the proxy, so the two never drift. No other module imports it today; when one must, it moves into the
|
|
// networking domain's package (research 081).
|
|
//
|
|
// **How a route travels.** A module that must be reachable requires `route` and says, in its manifest's
|
|
// `contributes.route`, one Request, or several by local name; Schema is that object's JSON schema. The seat
|
|
// mesh-provisioner composes each (its label joined to the node's domains into `name` and `internal-name`, its endpoint's port into
|
|
// `port`) and the seat mesh-provisioner carries the result in the consumer's plan entry as an opaque payload
|
|
// (mesh-sdk catalogue.PlanProvision.Contributed, in the generic catalogue.ContributedForm). Neither the seat nor its
|
|
// client knows a field of a route: route-proxy decodes each contribution with DecodeRequest, and refuses, saying why
|
|
// (EventRefused), what this contract does not admit.
|
|
//
|
|
// **Two name spaces, two authorities** (novox/hq ADR 0056, ADR 0138). `name` is public: served to anyone and
|
|
// certified by the public ACME directory (Let's Encrypt). `internal-name` is served only inside the private network
|
|
// and certified by the mesh's own authority. A route carries either, or both.
|
|
package contract
|
|
|
|
// Module is the module that provides a route, and Provision what it provides: what a plan's entry names when
|
|
// route-proxy is a route's provider.
|
|
const (
|
|
Module = "route-proxy"
|
|
Provision = "route"
|
|
)
|
|
|
|
// Version is the version of the Request form this package reads and writes.
|
|
const Version = 1
|
|
|
|
// The events route-proxy says (its manifest's `emits`), on mesh.mod.route-proxy.event.<type>, each with an Event.
|
|
const (
|
|
// EventServed: a name is now served by this proxy (it was not, or it is now served from other rules).
|
|
EventServed = "route.served"
|
|
// EventWithdrawn: a name this proxy served is served no more, because no plan gives it any longer.
|
|
EventWithdrawn = "route.withdrawn"
|
|
// EventRefused: a plan gives this proxy a route it does not serve, and Why says why.
|
|
EventRefused = "route.refused"
|
|
)
|
|
|
|
// Event is the body of every event route-proxy says: the proxy's machine, the name (empty for a refusal that named
|
|
// none), how far it reaches, and who asked it: the consumer module, its machine and the local name of its
|
|
// contribution. Why is set on a refusal alone.
|
|
type Event struct {
|
|
Proxy string `json:"proxy"`
|
|
Name string `json:"name,omitempty"`
|
|
Reach string `json:"reach,omitempty"`
|
|
Module string `json:"module,omitempty"`
|
|
Node string `json:"node,omitempty"`
|
|
Local string `json:"local,omitempty"`
|
|
Why string `json:"why,omitempty"`
|
|
}
|
|
|
|
// The tools route-proxy serves (its manifest's `tools`), each answering from its states RoutesState and UnroutedState.
|
|
const (
|
|
// ToolRoutes lists every name served, with RoutesArgs.
|
|
ToolRoutes = "route_proxy_routes"
|
|
// ToolRoute is one name in full, with RouteArgs.
|
|
ToolRoute = "route_proxy_route"
|
|
// ToolUnrouted lists the names asked for and not served, with RoutesArgs.
|
|
ToolUnrouted = "route_proxy_unrouted"
|
|
)
|
|
|
|
// RoutesArgs are ToolRoutes' and ToolUnrouted's arguments: Node narrows to the proxy on one machine, every machine
|
|
// when empty.
|
|
type RoutesArgs struct {
|
|
Node string `json:"node,omitempty"`
|
|
}
|
|
|
|
// RouteArgs are ToolRoute's arguments: the name, such as app.example.org, and optionally the machine whose proxy.
|
|
type RouteArgs struct {
|
|
Name string `json:"name"`
|
|
Node string `json:"node,omitempty"`
|
|
}
|