leaflow

type Call struct {
	// Service and Operation name the operation, as Services and Operations
	// report them. Both the contract's operationId and its command-line
	// spelling are accepted, because those are the two names in circulation.
	Service string

	Operation string

	// Arguments are shaped the way Operation.Schema says: path and query
	// parameters at the top level under the contract's own names, a request body
	// whole under "body".
	//
	// They are checked against the contract before anything is sent, so a call
	// that satisfies the schema is a call that will be tried.
	Arguments map[string]any

	// Token is this caller's credentials, overriding the client's default. In a
	// service this is where the request's own user arrives.
	//
	// It is a token and nothing more, so a refused one cannot be replaced: see
	// Credentials for the case where it can.
	Token Token

	// Credentials replaces Token for a caller whose tokens expire sooner than
	// the work outlives them.
	//
	// An access token is good for a day. A piece of work that waits on a human
	// can be paused for longer than that, and when it resumes the first request
	// it makes is the one that gets a 401. The transport already retries that
	// exactly once, after asking the credentials to drop what was refused — but
	// a Token has nothing else to offer and says so, which turns the retry off.
	//
	// Supplying something that can mint a fresh token turns it back on. The
	// alternative is that the caller's own retry has to know which errors mean
	// "expired", which is the knowledge this package exists to hold.
	Credentials transport.Credentials
}

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

type Group struct {
	Name string

	Description string

	Operations int
}

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

type Options struct {
	// Services limits the catalogue to these contracts. Empty means all of them.
	//
	// An unknown name is an error rather than an empty selection: a service that
	// exposes nothing looks identical to a working one until the first call.
	Services []string

	// ReadOnly drops every operation that is not a GET before any caller can see
	// it. It is how an assistant is handed the platform without being handed the
	// ability to change it.
	ReadOnly bool

	// AccessTokenOnly drops every operation that takes an account token, leaving
	// the ones an access token can call.
	//
	// The account face — registering, listing projects, minting project tokens —
	// only accepts a token that comes from a person's sign-in session, which a
	// service acting on someone's behalf does not have. Left in, those
	// operations are ones a model can find, call, and be refused by, with
	// nothing in the refusal explaining that they were never available.
	//
	// Naming the services to exclude would do the same thing today and would be
	// wrong the day the platform adds another one — silently, because a list of
	// names cannot notice that it is short. The contract states which token each
	// operation takes, so that is what this reads.
	AccessTokenOnly bool

	// Endpoints points at another deployment. The zero value uses the addresses
	// the contracts declare.
	Endpoints transport.Endpoints

	// Credentials is where tokens come from when a Call does not carry its own.
	//
	// A service leaves this nil and puts a Token on every Call, because every
	// call is a different person. A command line supplies its token manager here
	// instead: it serves one person, and it can renew and exchange, which a bare
	// token cannot. A Token satisfies this interface, so a single-tenant caller
	// can simply pass one.
	Credentials transport.Credentials

	// HTTP is the client requests go out on. Supply one to control timeouts,
	// proxies or tracing; nil gets a sixty-second default.
	HTTP *http.Client
}

type Result struct {
	// Status is the HTTP status. Worth having even on success: a 204 carries no
	// body, and "deleted" is otherwise indistinguishable from "returned nothing".
	Status int

	// Value is the decoded reply — map[string]any, []any or a scalar — or nil
	// when the operation returned no body.
	Value any
}

type Service struct {
	Name string

	// Title is the contract's own, which is what to show a person or a model.
	Title string

	// Contract is the version of the document this was read from.
	Contract string

	// Operations is how many this client exposes, which under ReadOnly is fewer
	// than the contract declares.
	Operations int

	// Groups are the resource groups within the service — Disk, Instance,
	// SecurityGroup — and are what to narrow by before knowing any operation
	// names.
	Groups []Group
}

type Token struct {
	// Access acts inside one project and is what almost every operation takes.
	// The contracts call it a project token: it names a project as well as a
	// person, which is why no request path carries a project id.
	Access string

	// Account is for the account face — registering, listing projects, minting
	// access tokens — and comes from a person's sign-in session. A service
	// acting on someone's behalf does not have one, which is what
	// AccessTokenOnly is for.
	Account string
}