cloud

type BrowserLogin ¶

type BrowserLogin struct {
	// Endpoint is the control plane being logged in to.
	Endpoint Endpoint
	// OpenURL is the browser launcher. Injectable so a test drives the
	// whole flow without opening a real browser.
	OpenURL func(string) error
	// Timeout bounds the wait for the browser. A login that hangs forever is
	// indistinguishable from one about to succeed.
	Timeout time.Duration
	// Out receives the "open this URL" notice.
	Out io.Writer
}

BrowserLogin runs the interactive half of `forge login`: the OAuth 2.0 authorization-code flow with PKCE (RFC 7636) against the endpoint's /oauth/authorize and /oauth/token, with a loopback redirect (RFC 8252).

The mechanics are forge/pkg/oauth2.LoopbackLogin, which `reliant auth login` also runs. forge depends on no reliant code, deliberately. A user deploying to hosted infra without the reliant harness must never have to install reliant first, so `forge login` stands alone.

func (b BrowserLogin) Run(ctx context.Context) (credentials.Credential, error)

type Caller ¶

type Caller interface {
	Call(ctx context.Context, procedure string, req, out any) error
}

Caller is the one method ResolveOrganization needs.

type Client ¶

type Client struct {
	Endpoint   Endpoint
	Credential Credential
	HTTP       *http.Client
	// contains filtered or unexported fields
}

Client calls a hosted control plane over Connect's HTTP+JSON binding: POST <base>/<package>.<Service>/<Method> with a JSON body and a JSON reply.

WHY HTTP+JSON AND NOT A GENERATED CLIENT. A generated client would mean vendoring the control plane's protos into forge, which is the one coupling that must not ship — it would make forge's deploy story specific to our control plane in exactly the way forge's External target is deliberately NOT specific to Fly.io. Connect's JSON binding is a documented, stable part of the protocol and needs nothing but net/http, so the wire contract stays a contract rather than a shared build dependency.

The cost is real and worth naming: forge does not get compile-time checking of request and response shapes against the server's protos. A server-side field rename surfaces as a missing value at runtime rather than a build failure. That is the accepted trade for independence, and it is why Call decodes into explicitly-declared local structs — the shape forge expects is written down in one place instead of inferred.

func NewClient(ep Endpoint, cred Credential) *Client

func (c *Client) Call(ctx context.Context, procedure string, req, out any) error

type Credential ¶

type Credential struct {
	Token  string
	Source CredentialSource
	// From is the human-readable origin: the flag name, the env var name,
	// the credentials file path, or the helper's description of the
	// session it used. Safe to print; never the token itself.
	From string
	// ExpiresAt is when the token stops being accepted, when known. Only a
	// helper's tokens carry one today; nil means unknown.
	ExpiresAt *time.Time
}

Credential is a resolved bearer token plus where it came from.

func ResolveCredential(flagToken string, ep Endpoint) (Credential, error)

type CredentialSource ¶

type CredentialSource string

CredentialSource says where a resolved credential came from. Commands print it so "which credential did that use" never requires guessing — the single most common confusion when a CI run and a laptop disagree.

const (
	SourceFlag  CredentialSource = "flag"             // --token
	SourceEnv   CredentialSource = "env"              // the declared token_env
	SourceLogin CredentialSource = "credentials file" // written by `forge login`
	// SourceHelper is a token the credential helper named by
	// $FORGE_CREDENTIAL_HELPER minted from a host application's session
	// (pkg/cloudcred). forge does not know which application; Credential.From
	// carries the helper's own description of it.
	SourceHelper CredentialSource = "credential helper"
)

type Declaration ¶

type Declaration struct {
	Endpoint string
	TokenEnv string
}

Declaration is the per-environment control-plane declaration, as read from the environment's rendered KCL.

Declared HERE, at the consumer, rather than importing the CLI's entity type: this package needs two strings, and taking a dependency on the renderer's struct would point the dependency the wrong way (cli depends on cloud, not the reverse) and drag the whole entity graph in behind it.

type Endpoint ¶

type Endpoint struct {
	// Env is the environment this endpoint was declared by. Carried so
	// error messages can name the KCL file to edit.
	Env string
	// URL is the base URL, trailing slash trimmed.
	URL string
	// TokenEnv is the env var NAME the credential is read from.
	TokenEnv string
}

Endpoint is one environment's resolved hosted control plane: where to send requests, and which env var holds the credential.

There is deliberately no package-level "current endpoint" and no way to set one. An Endpoint only ever comes from a specific environment's declaration, which is what makes two environments resolvable to two different endpoints in the same process — and what removes the class of bug where a command silently targets whatever was selected last.

func ResolveEndpoint(env string, decl *Declaration) (Endpoint, error)

type Error ¶

type Error struct {
	// HTTPStatus is the response status. Kept because a response that is
	// not a Connect envelope at all (a proxy's HTML error page) has no
	// code, and the status is then the only classification available.
	HTTPStatus int

	// Code is the Connect error code as its wire name: "already_exists",
	// "not_found", "failed_precondition", "unauthenticated". Empty when
	// the body was not a Connect envelope.
	Code string

	// Reason is the app-defined domain reason from ReasonHeader, e.g.
	// "promotion_conflict" or "rollout_in_flight". Empty when the server
	// sent none.
	//
	// THIS IS THE FIELD TO BRANCH ON. The Connect code says the category
	// (FailedPrecondition), and three different refusals share it; the
	// reason says which one, and is the server's committed contract.
	Reason string

	// Message is the server's own message, verbatim and untruncated. For
	// DISPLAY — never for control flow.
	Message string

	// Details are the Connect error details, each left in its wire form.
	//
	// NOT DECODED, and that is deliberate: decoding a google.protobuf.Any
	// would mean vendoring the control plane's protos into forge, which is
	// the one coupling forge's deploy story must not take on. Connect's
	// JSON binding includes a `debug` member carrying the message as
	// protojson when the server could produce it, so a caller reads the
	// payload as JSON (see DetailJSON) without a generated type.
	Details []ErrorDetail

	// Procedure and Endpoint are where this happened, for the message.
	Procedure string
	Endpoint  string
	// contains filtered or unexported fields
}

Error is a failed control-plane call, as a TYPE rather than a sentence.

WHY THIS EXISTS. Call used to flatten every failure into a formatted string, and callers then recovered the classification by searching that string — `strings.Contains(err.Error(), "already_exists")`. That is wrong in both directions. A server that improves its prose breaks forge's control flow, which is a silent break: the branch simply stops matching and the error falls through to a generic failure. And forge's OWN message text contains the words it searches for, so a message that merely mentions a code reads as that code.

Worse, the structured half was discarded entirely. A promote refusal carries a DeployPromoteRefusal detail naming the promotion that actually landed — exactly what a pipeline needs to print instead of "someone else moved prod" — and flattening to a string threw it away.

So every primitive maps REASONS, not message text, to exit codes.

func (e *Error) DetailJSON(typeName string) (json.RawMessage, bool)

func (e *Error) Error() string

func (e *Error) HasCode(code string) bool

func (e *Error) HasReason(reason string) bool

type ErrorDetail ¶

type ErrorDetail struct {
	// Type is the protobuf full name, e.g.
	// "controlplane.v1.DeployPromoteRefusal".
	Type string `json:"type"`
	// Value is the base64 (raw std, unpadded) proto binary.
	Value string `json:"value"`
	// Debug is the same message as protojson, present when the server had
	// descriptors for it. This is the member a forge caller reads.
	Debug json.RawMessage `json:"debug,omitempty"`
}

ErrorDetail is one Connect error detail in its wire form.