plugin

type Access string

type Answerer interface {
	// Answer is asked for something. Return [ErrNoAnswer] when there is nothing
	// worth saying — that is a normal outcome and the asker has its own
	// fallback — and [ErrNotConfigured] when the operator has not filled
	// something in.
	//
	// Missing the deadline is the one unforgivable failure: somebody is
	// waiting, and an answer after they stopped is worse than none. Watch
	// ctx.Done and give up.
	Answer(ctx context.Context, r Request) (Response, error)
}

type Asker interface {
	Connected(host Host)
}

type Caller struct {
	// DriverSlug and DriverName are the signed-in driver, or empty for nobody.
	// A driver is signed in only where the host holds a session for them, and
	// the host is the only thing that can mint one.
	DriverSlug string `json:"driver_slug,omitempty"`
	DriverName string `json:"driver_name,omitempty"`
	// AdminEmail is the signed-in operator, or empty.
	AdminEmail string `json:"admin_email,omitempty"`
	// Remote is where the request came from, as the host resolved it behind
	// whatever proxy the operator runs.
	Remote string `json:"remote,omitempty"`
}

type Capabilities struct {
	// Events are the kinds this plugin wants delivered. The host sends these
	// and no others.
	Events []EventKind `json:"events,omitempty"`
	// Requests are the kinds it will answer, each spelled "<this plugin's
	// name>.<what>". The host refuses to ask for anything else rather than
	// waiting out a deadline to find out.
	Requests []RequestKind `json:"requests,omitempty"`
	// Asks names the plugins this one asks questions of. It is a declaration
	// the operator reads at install — "payments asks drivers for information"
	// — and one the host enforces: a question to a plugin not named here is
	// refused before it is put.
	Asks []string `json:"asks,omitempty"`
	// Network reports that it calls something outside this machine. It is the
	// declaration that matters most, because it is the one that turns the
	// operator's data into somebody else's.
	Network bool `json:"network"`
	// Calls names what it calls: the hosts, as an operator would recognise
	// them — "api.anthropic.com". A plugin that declares Network without
	// naming anything is shown as one that does not say where the data goes,
	// which is what it is.
	Calls []string `json:"calls,omitempty"`
	// WritesFiles reports that it writes to disk.
	WritesFiles bool `json:"writes_files"`
	// ReadsDriverData reports that it uses the driver's name and record rather
	// than anonymous numbers.
	ReadsDriverData bool `json:"reads_driver_data"`
	// Database asks for tables of its own. The host creates a PostgreSQL role
	// and a schema for this plugin alone, applies whatever is in its
	// [MigrationsDir], and hands it the connection string in [EnvDatabaseURL].
	//
	// Unlike everything else here, this one is enforced. A plugin that does not
	// declare it is given no database and no role exists for it; a plugin that
	// does gets one it owns entirely and cannot reach out of. Uninstalling
	// drops both, so a plugin's data leaves with the plugin.
	Database bool `json:"database,omitempty"`
	// HTTP asks for a route of this plugin's own, at /plugin/<name>/. A plugin
	// that declares it must implement [Server]; one that does not is refused at
	// install rather than left as a link in the panel that answers 500.
	//
	// Like [Capabilities.Database] this one is enforced. A plugin that does not
	// declare it has no route and is never handed a request, so the surface a
	// plugin adds to the operator's server is the surface it asked for in
	// writing.
	HTTP *HTTPCapability `json:"http,omitempty"`
}

type Choice struct {
	// Value is what is stored. It is stable: renaming a label is cosmetic,
	// renaming a value orphans what the operator already chose.
	Value string `json:"value"`
	// Label is what the operator reads.
	Label string `json:"label"`
	// Note is the half-line under the label, for the difference between two
	// options that the labels alone do not make obvious. It may be empty.
	Note string `json:"note,omitempty"`
}

type Conditions struct {
	// Skies is the simulator's enum, 0 clear to 3 overcast, and Wetness its
	// own, 0 unknown to 7 very wet.
	Skies   int `json:"skies"`
	Wetness int `json:"wetness"`
	// WindKmh is km/h, Humidity a percentage, and the temperatures Celsius.
	WindKmh    float64 `json:"wind_kmh"`
	Humidity   float64 `json:"humidity"`
	TrackTempC float64 `json:"track_temp_c"`
	AirTempC   float64 `json:"air_temp_c"`
}

type Driver struct {
	// ID is this server's own identifier for the driver. It is stable and it
	// is the right key for a plugin's own cache.
	ID int64 `json:"id"`
	// Slug is the short, URL-safe name.
	Slug string `json:"slug"`
	// Name is what the driver calls themselves, and what a cue should use.
	Name string `json:"name,omitempty"`
	// Team is the team name, empty when they are not in one.
	Team string `json:"team,omitempty"`
}

type Event struct {
	// ID is unique to this delivery. It is the key to deduplicate on: a host
	// that restarts mid-dispatch may send the same event twice, and a plugin
	// that posts to a chat room should not post twice.
	ID string `json:"id"`
	// Kind is what happened.
	Kind EventKind `json:"kind"`
	// At is when the host dispatched it, not when the lap was driven — that is
	// in the facts.
	At time.Time `json:"at"`
	// Driver and Session are who and where.
	Driver  Driver  `json:"driver"`
	Session Session `json:"session"`
	// Lap is set when Kind is [EventLapCompleted], and nil otherwise.
	Lap *LapFacts `json:"lap,omitempty"`
	// Stint is set when Kind is [EventStintFinished], and nil otherwise.
	Stint *StintFacts `json:"stint,omitempty"`

	// Settings are the operator's answers for this plugin, already validated
	// against what it declared and with the defaults filled in. Credentials are
	// not here; they are in [Event.Secrets].
	Settings Values `json:"-"`
	// Secrets are the credentials this plugin declared, lent for this call.
	Secrets Secrets `json:"-"`
	// TokenCeiling is the most this call may spend, or zero for no ceiling
	// beyond the operator's daily cap. It is the core rationing its own money:
	// a plugin refuses before it sends rather than truncating afterwards.
	TokenCeiling int `json:"token_ceiling,omitempty"`
}

type EventKind string

type FuelSummary struct {
	UsedL      float64 `json:"used_l"`
	RemainingL float64 `json:"remaining_l"`
}

type HTTPCapability struct {
	// Title is what the panel calls the link to this plugin's pages. Empty
	// means the plugin's own name.
	Title string `json:"title,omitempty"`
	// Routes is every address this plugin serves. A plugin that declares none
	// is refused: asking for a URL without saying which is asking for all of
	// them.
	Routes []Route `json:"routes"`
}

type HTTPRequest struct {
	// Method is the HTTP method.
	Method string `json:"method"`
	// Path is what follows the plugin's own prefix, always beginning with a
	// slash. A plugin routes on this.
	Path string `json:"path"`
	// Query is the raw query string, without the question mark.
	Query string `json:"query,omitempty"`
	// Header is the request's headers, minus the host's own: no cookie of the
	// host's reaches a plugin, and a plugin sees only cookies it set itself.
	Header http.Header `json:"header,omitempty"`
	// Body is the request body, already capped by the host.
	Body []byte `json:"body,omitempty"`
	// Caller is who made it.
	Caller Caller `json:"caller"`
	// Prefix is where this plugin is mounted — "/plugin/results" — so that it
	// can build links and form actions that come back to itself.
	Prefix string `json:"prefix"`
	// BaseURL is the operator's public address, for the links a plugin sends
	// somewhere else and expects a browser back from.
	BaseURL string `json:"base_url"`
	// Settings and Secrets are this plugin's configuration, on the same terms
	// as every other call.
	Settings Values  `json:"settings,omitempty"`
	Secrets  Secrets `json:"-"`
}

type HTTPResponse struct {
	// Status is the HTTP status code. Zero is 200.
	Status int `json:"status,omitempty"`
	// Header is what to write. The host refuses the headers that are its own
	// to decide, and lets a plugin set only its own cookies.
	Header http.Header `json:"header,omitempty"`
	// Body is the response body.
	Body []byte `json:"body,omitempty"`
	// SignIn asks the host to establish a driver session for this browser, by
	// the driver's slug.
	//
	// It is how a plugin that authenticates drivers hands the result back. The
	// plugin says who; the host checks the driver exists, mints the session and
	// sets the cookie. A plugin never sees a session token and cannot make one,
	// so the worst a broken one can do is name the wrong driver — which is bad,
	// and is not the same as forging sessions for a server it is not installed
	// on.
	SignIn string `json:"sign_in,omitempty"`
	// SignOut ends whatever driver session this browser has.
	SignOut bool `json:"sign_out,omitempty"`
	// Usage is what serving the request cost, if anything.
	Usage Usage `json:"usage,omitzero"`
}

type Host interface {
	// Ask puts a question to another plugin and waits for the answer.
	//
	// kind names the plugin that answers it — "drivers.lookup" is answered by
	// the plugin called drivers — and it must be a plugin this one's manifest
	// says it asks, or the host refuses with [ErrNotAllowed]. payload is
	// whatever the two plugins agreed on; the host does not read it. The
	// answer is the other plugin's payload, or one of the errors the contract
	// names: [ErrUnavailable] when nothing is running to answer,
	// [ErrUnsupported] when the plugin does not answer that kind,
	// [ErrNoAnswer] when it had nothing to say, [ErrNotConfigured] when the
	// operator has not set it up, and ctx's own error when the deadline
	// passed.
	Ask(ctx context.Context, kind string, payload json.RawMessage) (json.RawMessage, error)
}

type Kind string

type LapFacts struct {
	// Number is the simulator's lap counter and LapMs the lap time.
	Number int `json:"number"`
	LapMs  int `json:"lap_ms"`
	// Kind is how the lap counts.
	Kind LapKind `json:"kind"`
	// DeltaMs is the lap time against [LapFacts.Reference], in milliseconds:
	// positive is slower. It means nothing when Reference is empty.
	DeltaMs int `json:"delta_ms,omitempty"`
	// Reference names what the delta is against, in words a driver would use —
	// "your best lap", "the class best". Empty means there was nothing to
	// compare against, which happens on a circuit nobody has driven here yet
	// and is not a failure.
	Reference string `json:"reference,omitempty"`
	// PersonalBest reports that this is the driver's best lap here.
	PersonalBest bool `json:"personal_best,omitempty"`
	// Corners is the lap's corner analysis, as the client sent it and the
	// server stored it: a JSON array, worst corner first, in the schema the
	// protocol module's wire.Corner describes. It is absent when the client
	// sent no corner detection, and a plugin must cope with that rather than
	// inventing a turn number.
	//
	// It is a document and not a struct so that this contract does not have to
	// know what a corner is. A plugin decodes the schema it understands and
	// ignores the rest.
	Corners json.RawMessage `json:"corners,omitempty"`
	// Position is the race picture, absent outside a race.
	Position *Position `json:"position,omitempty"`
	// SpokenLap is the lap time already rendered into speakable words — "one
	// minute 31.2 seconds". It exists because a speech engine reading "91240"
	// produces something nobody wants in their ear, and the client can render
	// it correctly while a model cannot be trusted to.
	SpokenLap string `json:"spoken_lap,omitempty"`
	// StartedAt is when the lap began.
	StartedAt time.Time `json:"started_at"`
}

type LapKind string

type Manifest struct {
	// Name identifies the plugin everywhere — the directory, the settings, the
	// metering rows, the panel. Lowercase letters, digits, underscores and
	// hyphens, and permanent: renaming one is installing a different plugin.
	Name string `json:"name"`
	// Version is the plugin's own version, for the operator and the
	// marketplace. Its spelling is the author's business.
	Version string `json:"version"`
	// Author is who to blame, and who the operator is trusting.
	Author string `json:"author"`
	// Description is one line of what it does, shown in the panel.
	Description string `json:"description"`
	// InterfaceVersion is the version of this contract the plugin was built
	// against. It must equal the host's [InterfaceVersion] exactly; see
	// [CheckVersion].
	InterfaceVersion int `json:"interface_version"`
	// Binary is the executable to run, relative to the manifest and with no
	// directory separators in it. Empty means [Manifest.Name]; on Windows a
	// ".exe" is added when it is not already there.
	Binary string `json:"binary,omitempty"`
	// Capabilities are what it does.
	Capabilities Capabilities `json:"capabilities"`
}

type Plugin interface {
	// Settings declares what the operator has to configure. The host asks once
	// when the plugin starts, stores the answer, and renders the form from it.
	//
	// It must not depend on configuration — a fresh installation has none — and
	// it must be stable: a setting that appears and disappears between calls is
	// a form that loses what the operator typed.
	Settings(ctx context.Context) ([]Setting, error)

	// Notify is told that something happened. The host does not wait for this
	// before carrying on with its own work, so taking a while here costs
	// nothing but the plugin's own timeliness.
	//
	// The returned [Usage] is what the event cost. Return the zero value when
	// it cost nothing. An error is logged against the plugin and nothing else:
	// there is no retry, because an event that matters enough to retry is a
	// question another plugin should be asking.
	Notify(ctx context.Context, e Event) (Usage, error)
}

type Position struct {
	// ClassPos is the position in the driver's own class.
	ClassPos int `json:"class_pos"`
	// GapAheadMs and GapBehindMs are the gaps either side, in milliseconds.
	// Zero means there is nobody there.
	GapAheadMs  int `json:"gap_ahead_ms,omitempty"`
	GapBehindMs int `json:"gap_behind_ms,omitempty"`
}

type Request struct {
	// ID is unique to this call, for the plugin's own logging and cache.
	ID string `json:"id"`
	// Kind is what is wanted, spelled "<this plugin's name>.<what>".
	Kind RequestKind `json:"kind"`
	// From is the plugin that asked, as the host knows it. It is the host's
	// word and cannot be set by the asker.
	From string `json:"from"`
	// Hops is how many plugins this question has already passed through,
	// counting the asker. A plugin answering it that asks something else in
	// turn does not have to add to it: the host counts.
	Hops int `json:"hops,omitempty"`
	// Deadline is when the host stops waiting. It is also the deadline on the
	// context, repeated here so a plugin deciding how hard to try has the
	// number without asking the context for it.
	Deadline time.Time `json:"deadline"`
	// Payload is the question, in whatever shape this kind takes. It is a
	// document and not a struct so that this contract does not have to know.
	Payload json.RawMessage `json:"payload,omitempty"`
	// Settings and Secrets are the answering plugin's own configuration, on
	// the same terms as every other call.
	Settings Values  `json:"-"`
	Secrets  Secrets `json:"-"`
	// TokenCeiling is the most this call may spend, or zero for no ceiling
	// beyond the operator's daily cap.
	TokenCeiling int `json:"token_ceiling,omitempty"`
}

type RequestKind string

type Response struct {
	// Kind echoes the request, so a caller holding several in flight can tell
	// them apart without keeping the map.
	Kind RequestKind `json:"kind"`
	// Payload is the answer, in whatever shape this kind takes. Empty is not
	// an answer — return [ErrNoAnswer] instead — because a caller must be able
	// to tell "nothing to say" from "here is nothing".
	Payload json.RawMessage `json:"payload,omitempty"`
	// Usage is what the call cost. A plugin that leaves this zero is telling
	// the core it spent nothing, and the core will believe it.
	Usage Usage `json:"usage"`
}

type Route struct {
	// Path is the address, relative to the plugin's own prefix and beginning
	// with a slash. "/" covers everything the plugin serves.
	Path string `json:"path"`
	// Access is what the host requires of a caller before it forwards.
	Access Access `json:"access"`
	// Reason is why this route decides for itself. It is required for
	// [AccessCustom] and meaningless otherwise: that is the one mode where the
	// host checks nothing, so it is the one an operator has to be told about
	// in words before they enable the plugin.
	Reason string `json:"reason,omitempty"`
}

type Secret struct {
	// contains filtered or unexported fields
}

type Secrets map[string]Secret

type Server interface {
	// ServeHTTP answers one request. The deadline is on the context and the
	// host answers for a plugin that misses it, so a slow page is a slow page
	// and not a connection somebody else is waiting behind.
	//
	// It is named for [net/http.Handler] because that is the model — a request
	// in, a response out, and nothing held between them — and to keep it apart
	// from [Serve], which starts the process.
	ServeHTTP(ctx context.Context, r HTTPRequest) (HTTPResponse, error)
}

type Session struct {
	// StintID is the capture this belongs to, a UUID.
	StintID string `json:"stint_id"`
	// Sim is the simulator's own identifier.
	Sim string `json:"sim"`
	// Track is the display name and TrackID the simulator's stable identifier.
	Track   string `json:"track"`
	TrackID string `json:"track_id"`
	// Car is the car's display name and CarClass the class it runs in.
	Car      string `json:"car"`
	CarClass string `json:"car_class,omitempty"`
	// Type is what the session was.
	Type SessionType `json:"type"`
	// StartedAt is when the stint began.
	StartedAt time.Time `json:"started_at"`
}

type SessionType string

type Setting struct {
	// Name is the key the value is stored under and the key the plugin reads
	// it back by. It is lowercase letters, digits and underscores, and it is
	// permanent: changing it loses whatever the operator had set.
	Name string `json:"name"`
	// Label is the field's name in the panel, in sentence case, without a
	// trailing colon.
	Label string `json:"label"`
	// Help is the line under the field. It is what an operator who has never
	// seen this plugin needs in order to answer, and it is worth writing
	// properly: it is the only documentation most of them will read.
	Help string `json:"help,omitempty"`
	// Kind is what it holds.
	Kind Kind `json:"kind"`
	// Required refuses an empty value. A plugin with an unfilled required
	// setting is shown as needing attention and is not called.
	Required bool `json:"required,omitempty"`
	// Default is the value used when the operator has set none. It must be
	// empty for [KindSecret]: a default credential is not a thing.
	Default string `json:"default,omitempty"`
	// Choices are the options of a [KindChoice] setting, in the order the
	// panel shows them. Ignored for every other kind.
	Choices []Choice `json:"choices,omitempty"`
	// Placeholder is the grey text in an empty field, for the shape of the
	// answer rather than an example that someone will paste verbatim.
	Placeholder string `json:"placeholder,omitempty"`
}

type StintFacts struct {
	// Laps is every lap driven and CleanLaps the ones that counted.
	Laps      int `json:"laps"`
	CleanLaps int `json:"clean_laps"`
	// Incidents is the simulator's own count.
	Incidents int `json:"incidents"`
	// BestLapMs and AvgLapMs are over the counted laps.
	BestLapMs int `json:"best_lap_ms"`
	AvgLapMs  int `json:"avg_lap_ms"`
	// ConsistencyPct is 0 to 100: how tightly the counted laps cluster. It is
	// the single most useful number about a stint and the one a driver cannot
	// feel.
	ConsistencyPct int `json:"consistency_pct"`
	// TopSpeedKmh is the fastest the car went.
	TopSpeedKmh int `json:"top_speed_kmh"`
	// Fuel and Tyres are what the car had left and how hard it was working.
	Fuel  FuelSummary `json:"fuel"`
	Tyres TyreSummary `json:"tyres"`
	// Setup is the car the driver drove, as the client sent it and the server
	// stored it: a JSON document in the schema the protocol module's
	// wire.CarSetup describes. It is on the stint and not on the lap because it
	// is one per sitting. It is absent when the simulator published none, which
	// is normal and not a failure, and a plugin must say nothing about the
	// setup rather than guess at one.
	//
	// A setup sheet is car-specific, so this was never going to be a fixed
	// struct; it is a document for the same reason [LapFacts.Corners] is.
	Setup json.RawMessage `json:"setup,omitempty"`
	// Conditions is the weather it was driven in.
	Conditions Conditions `json:"conditions"`
	// FinishedAt is when the stint ended.
	FinishedAt time.Time `json:"finished_at"`
}

type TyreSummary struct {
	LF float64 `json:"lf"`
	RF float64 `json:"rf"`
	LR float64 `json:"lr"`
	RR float64 `json:"rr"`
}

type Usage struct {
	// Job is what the call was for. For a request it is the request kind; for
	// an event a plugin names its own work. It is what the operator sees when
	// they ask where the money went, so "cue.training" is useful and "call" is
	// not.
	Job string `json:"job,omitempty"`
	// Model is the model the tokens were spent on, when there was one. It is
	// free text because the plugin knows the vendor and the core does not.
	Model string `json:"model,omitempty"`
	// InputTokens and OutputTokens are counted the way the vendor counts them,
	// so that the figure in the panel matches the figure on the bill.
	InputTokens  int64 `json:"input_tokens,omitempty"`
	OutputTokens int64 `json:"output_tokens,omitempty"`
	// Cached reports that the answer came from the plugin's own cache. It is
	// recorded because a cache that is not measured is a cache nobody can tell
	// is working.
	Cached bool `json:"cached,omitempty"`
}

type Values map[string]string

type VersionError struct {
	// Plugin is the name from the manifest, for the message.
	Plugin string
	// Built is the interface version the plugin declared.
	Built int
	// Host is the interface version this host implements.
	Host int
}