rigclient

type API struct {
	// BasePath is the prefix every route sits under, for example "/api/v1".
	BasePath string
	// Auth is the authentication profile, or nil for a project with none.
	Auth *AuthProfile
	// Revision is the date the API surface this client was generated from last
	// changed. It is sent on every request, which is how a server's logs can
	// answer how old the oldest caller still calling is.
	Revision string
	// RevisionHeader is where Revision is sent — the same header the server it
	// was generated with reads.
	RevisionHeader string
}

type APIKey string

type AuditQuery struct {
	AccountID *uuid.UUID
	Event     *string
	Outcome   *string
	Since     *time.Time
	Until     *time.Time

	// Limit is the page size, defaulting to 50 and capped at 500. Offset is
	// where the page starts.
	Limit  *int
	Offset *int
}

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

type AuthProfile struct {
	// BasePath is where the endpoints sit, for example "/auth".
	BasePath string

	// AccessTTL is the lifetime of the token that travels on every request.
	AccessTTL time.Duration
	// RefreshTTL is how long an ordinary session lasts.
	RefreshTTL time.Duration
	// RememberTTL is how long one lasts when somebody asked to stay signed in.
	RememberTTL time.Duration
	// RotationLeeway is how long a refresh token stays usable after it has been
	// exchanged. It is also what this package refreshes ahead by: the server
	// having decided how much slack a swap deserves, a client has no business
	// picking a different number.
	RotationLeeway time.Duration
	// IdentityTTL is the lifetime of the tenant-less credential somebody holds
	// between signing in and picking a tenant.
	IdentityTTL time.Duration
	// CacheTTL is how long the server may go on answering out of memory after an
	// invalidation it never received. Zero means it caches nothing and every
	// request reads the row.
	//
	// It is not how long a revocation takes to take effect, and reading it that
	// way is the mistake worth naming. The server publishes an invalidation on
	// the transaction that revokes something, so the ordinary answer is "at
	// once"; this is the worst case for a replica that had lost the channel at
	// that moment.
	//
	// A client cannot act on either number. It is here so that somebody reading
	// the generated document can say how stale an answer could possibly be.
	CacheTTL time.Duration

	// TenantHeader is the header a sign-in names its tenant with, when the
	// project resolves tenants that way. Empty when it does not.
	TenantHeader string
	// TenantQuery is the query parameter that does the same, for the projects
	// configured to read one.
	TenantQuery string

	// HasEmailCode is POST <base>/email-code and POST <base>/email-code/verify:
	// whether this deployment signs anybody in with a mailed code.
	HasEmailCode bool
	// HasTenantCreation is POST <base>/tenants.
	HasTenantCreation bool
	// HasIdentitySessions is the tenant picker: /me/tenants and its siblings,
	// which exist only where identity sessions are configured.
	HasIdentitySessions bool
	// HasAPIKeys is the /api-keys routes.
	HasAPIKeys bool

	// OAuthProviders are the provider names with a sign-in route, in the order
	// the project listed them. Empty when there is no provider sign-in.
	OAuthProviders []string
}

type CallOption func(*call)

type Config struct {
	// BaseURL is the origin the API is served from, for example
	// "https://api.example.com". A path on it is kept and the API's own base
	// path is appended, so a server behind "/gateway" is a base URL and not a
	// special case.
	BaseURL string

	// HTTPClient is the transport. The default has a thirty-second timeout,
	// which is a limit on the whole exchange rather than on a stalled read —
	// use a context for anything finer.
	//
	// Thirty seconds is right for a JSON call and wrong for a file, and a
	// context cannot raise it. A client that uploads or downloads at size wants
	// [WithTimeout] on those calls rather than a longer ceiling on every one.
	HTTPClient *http.Client

	// Credential is what authorizes each request: [StaticToken], [APIKey], or a
	// [Session] that keeps itself fresh. Nil sends no Authorization header,
	// which is what a public API or a header-authenticated demo wants.
	Credential Credential

	// Header is sent on every request. It is where a tenant header, a trace
	// header, or anything else a deployment adds belongs.
	Header http.Header

	// UserAgent identifies the caller in the server's logs. An SDK that does not
	// say who it is turns "which integration is hammering us" into a guess.
	UserAgent string

	// RequestID supplies the value of the request-ID header, so a client-side
	// log line and a server-side one can be joined. Nil sends none, and the
	// server generates its own.
	RequestID func() string

	// RequestIDHeader defaults to X-Request-Id, which is what the generated
	// server reads.
	RequestIDHeader string

	// OnRateLimit is called with what each response said about the caller's
	// budget, when the server said anything at all.
	//
	// It is the other half of rate limiting, and the half a client can act on.
	// A 429 is already handled without it — the SDK reads Retry-After and backs
	// off — but by then the call has been refused. These numbers arrive on every
	// response, so a caller that watches them can slow down, shed work, or raise
	// an alarm while its calls are still succeeding.
	//
	// Deliberately a callback and not automatic pacing. A client library that
	// silently slept because Remaining was low would turn a batch job's
	// throughput into a mystery, and it cannot know whether this caller would
	// rather go slower or fail sooner. The numbers are handed over; the policy
	// is the application's.
	//
	// Called on the request's own goroutine, once per attempt, before the call
	// returns. Keep it quick and do not call back into the client from it.
	OnRateLimit func(RateLimitStatus)

	// Revision overrides the API revision this client says it was built against.
	//
	// Almost nobody should set it. The generated client carries the revision
	// from the document it was generated from, which is the honest answer and
	// the one the server's logs are for; this is here for a client somebody
	// assembled by hand.
	Revision string

	// RevisionHeader overrides where the revision is sent. Empty takes the
	// generated client's, which is what the server it was generated with reads.
	RevisionHeader string

	// Now is the clock, for a test that has to cross a token expiry without
	// waiting ten minutes for one. Nil is [time.Now].
	Now func() time.Time

	// Trace runs one piece of work inside a span, and is how a caller that
	// traces gets this client's calls into the same trace as everything else it
	// does:
	//
	//	Trace: observe.Call,
	//
	// A function rather than a tracer, because this module is imported by every
	// generated client and most of them do not want an OpenTelemetry dependency
	// — the same argument that keeps otel out of rig/runtime. Anything with
	// this shape works; rig/observe supplies one.
	//
	// Two spans per call, and the nesting is the point. The outer one is the
	// operation, named by [Op.Name]; the inner ones are the attempts, and one
	// call can be several — the QUERY a proxy refused, the POST to the alias,
	// the send after a credential refreshed, and every [Retry]. Tracing the
	// attempts alone would show one call as a handful of unrelated requests.
	//
	// Nil traces nothing, which is what a client that was never told about
	// tracing does.
	Trace func(ctx context.Context, name string, f func(context.Context) error) error

	// Retry is how a call the server could not answer is sent again. The zero
	// value sends a call up to four times with a jittered backoff — a read and a
	// delete because they are repeatable by nature, a write because the SDK names
	// it with an Idempotency-Key first. A form body is the exception and is never
	// repeated. See [Retry].
	Retry Retry
}

type Content struct {
	// Body is the bytes. Close it.
	Body io.ReadCloser

	// ContentType is what the server says the bytes are: the type it sniffed
	// when the file was uploaded, never the one the client claimed when it sent
	// it.
	ContentType string

	// Length is the number of bytes in Body, or -1 when the server did not say.
	// On the 206 that [WithRange] asks for it is the length of the range and
	// not of the file.
	Length int64

	// Filename is the name from Content-Disposition, or empty. It is a
	// suggestion and not a path: a program writing it to disk decides where, and
	// sanitizes what.
	Filename string

	// ETag identifies this version of the file, for a later call to quote back
	// through [WithIfNoneMatch].
	ETag string

	// Status is 200 for the whole file, 206 for the range [WithRange] asked
	// for, and 304 for a body the caller already has — in which case Body is
	// empty and closing it is all there is to do with it.
	Status int
}

type Credential interface {
	// Apply adds whatever the request needs — an Authorization header, in every
	// implementation here. It may block, and it may fail, and a failure means
	// the request is not sent.
	Apply(ctx context.Context, r *http.Request) error
}

type Error struct {
	// Status is the HTTP status, for the cases where only it is meaningful — a
	// 502 from something in front of the server, say, which carries no code.
	Status int
	// Code is the machine-readable reason. Empty when the failure came from
	// something that is not a rig server.
	Code rigerr.Code
	// Message is prose, for a person. It is not meant to be parsed.
	Message string
	// RequestID correlates this failure with the server's logs. Quoting it in a
	// bug report is the difference between a search and a guess.
	RequestID string
	// Fields is present when the failure was validation, and is shaped like the
	// request body that failed — one member per field, holding what was wrong
	// with it.
	//
	// These are the bytes. A call made through a generated method comes back as
	// that method's own error — client.TodoCreateError, which is a [Failure] —
	// and has them decoded already. [FieldsAs] is for a call made by hand.
	Fields json.RawMessage
	// RetryAfter is how long the server asked the caller to wait, from the
	// header of the same name, in either form it takes: the seconds rig's own
	// server sends, and the date something in front of it might. Zero when it
	// said nothing, or asked for a moment already past.
	//
	// The SDK honours it for a call it may repeat — see [Retry] — so this is
	// mostly for the refusal that came back anyway, where the interval was
	// longer than the call had left to spend.
	RetryAfter time.Duration
	// Body is the start of the raw response, kept for a failure that decoded
	// into nothing useful — a proxy's HTML error page, say. It is bounded even
	// where the read was not, so a large validation failure is complete in
	// Fields and cut short here.
	Body string
}

type Failure[F any] struct {
	*Refusal

	// Fields is what was wrong with each member of the body, and is nil when the
	// refusal was not about the body — which is every refusal but a 422. A 404
	// carries a code and a message and nothing to attach to a control, and a
	// zero-valued shape there would look like a body nobody complained about.
	//
	// It shadows [Error.Fields], which is the point: the typed value is what a
	// caller wants, and the bytes are still under Refusal for anything that
	// wants those.
	Fields *F
}

type Multipart struct {
	// JSON is encoded into the part named "json". Nil leaves the part out,
	// which is what a bare upload does: there is no row to send, only bytes for
	// a row that already exists.
	JSON any

	// Files are the file parts, in the order they are written.
	Files []Upload
}

type Op struct {
	// Name is the operation this call is, as the document named it —
	// "listTodos", "createTodo". The generated method fills it in.
	//
	// It is what a call's span is called, which is why it is a field rather
	// than something derived from Method and Path: the path here already has
	// its identifiers substituted, so a name built from it would be a new name
	// for every row anybody ever fetched.
	Name string

	Method string
	Path   string
	Query  url.Values
	// Body is encoded as JSON when it is not nil. A pointer to a struct and the
	// struct itself both work; nil means no body at all, which is not the same
	// as an empty object.
	Body any

	// Multipart is a form body, sent instead of Body.
	//
	// The two are exclusive rather than ordered: an Op carrying both is a
	// generated method with a bug in it, and it is reported rather than resolved
	// by a precedence somebody would have to look up.
	//
	// A form is streamed, so it is sent chunked and carries no Content-Length.
	// Computing the envelope's length up front is possible and would mean
	// buffering nothing useful for a header almost nothing needs; an
	// intermediary that insists on one is a deployment problem, and buffering
	// every upload to satisfy it is not a trade this makes.
	Multipart *Multipart

	// Accept is the media type this call will take back. Empty means
	// application/json, which is every endpoint but a download: a download
	// answers with whatever the file turned out to be, and a client that
	// insisted on JSON would be asking for the one thing it is not.
	Accept string

	// Fallback is the path to POST to when Method is QUERY and something between
	// here and the server refuses it — the `_search` alias the router mounts
	// beside the QUERY route. Empty means there is none, and a refusal is
	// reported rather than worked around.
	Fallback string

	// Root says the path is relative to the server rather than to the API's base
	// path. The authentication endpoints are: /auth/login is mounted beside
	// /api/v1 and not inside it, because a sign-in is not a version of the
	// application's API.
	Root bool
}

type Page[T any] struct {
	Items []T
	// Total is every row matching the query, ignoring pagination. It is what
	// says whether there is another page.
	Total int64
	// Offset is where this page started, as the server reported it.
	Offset int
}

type RateLimitStatus struct {
	// Op is the operation that was called, as the document names it —
	// "listTodos". A gauge keyed on it says which call is spending the budget.
	Op string

	// Limit is how many calls the window allows, and Remaining how many are
	// left. Remaining is zero on the response that was refused.
	Limit     int
	Remaining int

	// ResetAfter is how long until the window frees, and is only stated on a
	// refusal — an allowed response says how much is left but not when it comes
	// back. Zero means the server did not say.
	ResetAfter time.Duration

	// Refused is true when this response was the 429 rather than a call that
	// went through.
	Refused bool
}

type Reauthorizer interface {
	// Reauthorize reports whether it did something worth retrying for.
	Reauthorize(ctx context.Context) (bool, error)
}

type Refusal = Error

type Retry struct {
	// Attempts is how many times a call is sent, the first try included. Zero
	// takes [DefaultAttempts]; one sends it once and reports whatever came back.
	//
	// Four is three retries, and the first of them is immediate — see
	// [Retry.Base]. Beyond that a caller is waiting seconds on a call that was
	// probably going to fail anyway, and the calls worth waiting longer on are
	// the ones a caller knows about, which is what [WithRetry] is for.
	Attempts int

	// Base is the first backoff window, doubling per attempt after it. Zero
	// takes [DefaultRetryBase].
	//
	// The first retry does not use it: it goes out immediately, because the
	// commonest retryable failure there is — a pooled connection the server had
	// already closed — is fixed by opening another one, and waiting a second
	// first would only be slower. Everything after that waits.
	//
	// A wait is half the window plus a random share of the other half, rather
	// than the window. The failures worth retrying arrive in crowds — one
	// instance drained, one limiter window closed — and a hundred callers who
	// all waited exactly one second come back together and refuse the server
	// together, which is the thing the interval was for.
	Base time.Duration

	// Cap bounds one backoff window, however many attempts have already failed.
	// Zero takes [DefaultRetryCap].
	//
	// It does not bind at the default attempt count, which is why it is a field
	// rather than a number anybody has to choose: a caller who raises Attempts
	// to eight is asking for eight tries, not for a two-minute sleep in the
	// middle of them.
	Cap time.Duration
}

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

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

type StaticToken string

type Upload struct {
	// Field is the part's name, which is the field the server binds the bytes
	// to. A generated method fills it in from the document, through [Part];
	// setting it by hand is for a client somebody assembled themselves.
	Field string

	// Name is what the file is called. The server records it on the row and puts
	// it in the download path, and it never becomes the storage key — so a name
	// with a slash in it is a strange name and not a way out of the bucket.
	Name string

	// ContentType is what the caller claims the bytes are. Empty sends none, and
	// it makes little difference either way: the server sniffs the content and
	// the sniffed type is the one it stores and the one it serves back.
	ContentType string

	// Body is the bytes. A reader that can also seek can be sent twice, which is
	// what a credential refresh mid-upload needs — see [ErrCannotRetry].
	Body io.Reader
}