// 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"`
}