78 lines
4.0 KiB
Go
78 lines
4.0 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").
|
|
//
|
|
// **Published by the repository that holds route-proxy, as its own Go module**, versioned by tags of the form
|
|
// `modules/route-proxy/contract/vX.Y.Z`, the subdirectory form Go's module system expects, the same way mesh-sdk is
|
|
// published (`go/vX.Y.Z`). A module that asks a route, reads what the proxy serves or hears its events imports this
|
|
// package; nothing imports the repository. Standard library only, so a consumer takes nothing else with it.
|
|
//
|
|
// **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 controller
|
|
// 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"`
|
|
}
|