platform

package
v0.13.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 20, 2026 License: Apache-2.0 Imports: 35 Imported by: 0

Documentation

Overview

Package platform signs a builder in to the aicoded platform and keeps the sign-in: aicoded login, logout and whoami, and the token that other commands send to the platform. It signs in with OAuth 2.1, in the browser through a loopback redirect (RFC 8252) or with a code entered on any device (RFC 8628). It also calls the builder API, which aicoded publish and status use, and cleans every text of its answers before anyone prints it.

Index

Constants

View Source
const DefaultAddress = "https://api.aicoded.cloud"

DefaultAddress is the platform's address when AICODED_PLATFORM is not set.

View Source
const MaxBundle = 32 << 20

MaxBundle is the size of the largest bundle the platform takes: 32 MiB.

View Source
const MaxRows = 1000

MaxRows is the most rows a read of logs or spans answers.

Variables

View Source
var Envs = []string{"preview", "production"}

Envs are the environments of an app on the platform whose logs and traces can be read.

View Source
var ErrBaseChanged = errs.New("E-PUB-010", "another publish of the app changed the commit whose history the platform holds while this one was sent",
	Fix("E-PUB-010"))

ErrBaseChanged is the error of CreatePublish when another publish of the app changed its base after App returned it: the bundle must be made again from the new base.

View Source
var ErrCancelled = errors.New("sign-in cancelled")

ErrCancelled is Login's error when its context ends before the sign-in does.

View Source
var ErrNoOrg = errors.New("no organisation to sign in to")

ErrNoOrg is Login's error when it has no organisation to sign in to: the first login needs one.

View Source
var (
	// PublishID matches the id of a publish.
	PublishID = regexp.MustCompile(`^pub_[a-z2-7]{26}$`)
)
View Source
var TraceID = regexp.MustCompile(`^[0-9a-f]{32}$`)

TraceID matches a trace id: 32 of 0-9 and a-f.

Functions

func Address

func Address() (string, error)

Address returns the platform's address from AICODED_PLATFORM, DefaultAddress when it is not set, written scheme://host, without the port of an https address when it is 443. It must be https, or http to 127.0.0.1 with a port, with no user, path, query or fragment; anything else is E-CLI-005, which does not quote the value, since it could hold a password.

func Delete

func Delete(address string) error

Delete deletes the credentials for the platform at address, and the file when it keeps no others, while it holds the lock on the file.

func Fix

func Fix(code string) string

Fix returns the fix of the code of publishing, or the fix on the page of the error catalogue of another code, or the advice to read its docs page.

func Save

func Save(address string, cr Credentials) error

Save keeps cr as the credentials for the platform at address, in a file only the user can read, in a folder only the user can open, while it holds the lock on the file. A folder that others can open is E-CLI-007.

func ValidOrg

func ValidOrg(s string) bool

ValidOrg reports whether s can name an organisation: 2 to 39 lowercase letters, digits and dashes, starting with a letter or digit.

func When

func When(name, s string, now time.Time) (time.Time, error)

When reads the time that name, such as --since, gives in s: in RFC 3339, or a while before now, such as 90s, 30m, 6h or 2d. An empty s is the zero time.

Types

type App

type App struct {
	Name     string
	Archived bool
	// Base is the commit whose history the platform holds, which a publish need not send again,
	// or "".
	Base string
	// Last is the app's latest publish, or nil.
	Last *Last
}

App is an app of the builder's organisation.

type Client

type Client struct {
	// HTTP makes the requests to the platform. It must not follow redirects.
	HTTP *http.Client
	// Timeout is how long a sign-in in the browser may take.
	Timeout time.Duration
	// contains filtered or unexported fields
}

Client signs a builder in to the platform at one address and keeps the sign-in.

func New

func New(address string, out io.Writer) *Client

New returns a client of the platform at address, which Address returned, that gives a sign-in in the browser 5 minutes. It tells the person what to do to sign in on out.

func (*Client) App

func (c *Client) App(ctx context.Context, name string) (app App, found bool, err error)

App returns the app of the builder's organisation named name; found is false when there is none. Another builder's app is E-PUB-005, and an app the builder owns that is archived may be E-PUB-006, as the platform's answer says.

func (*Client) CreatePublish

func (c *Client) CreatePublish(ctx context.Context, u Upload) (Created, error)

CreatePublish sends the upload to the delivery pipeline and returns the new publish. The first publish of a name creates the app. A bundle whose prerequisite is no longer the app's base is ErrBaseChanged; the other refusals have the code the platform gives, E-PUB-005 to E-PUB-010. Its meta holds the key migration only with a draft, and always the key release, so that a platform that does not hold publishes refuses the upload rather than release it.

func (*Client) Login

func (c *Client) Login(ctx context.Context, org string, device bool) (Whoami, error)

Login signs in to the organisation org: in a browser on this computer, or, with device, with a code entered in a browser on any device. An empty org is the organisation of the last sign-in; without one, Login returns ErrNoOrg. It keeps the new sign-in, revokes the one it replaces, and returns who it is for. When ctx ends first, it returns ErrCancelled.

func (*Client) Logout

func (c *Client) Logout(ctx context.Context) (signedIn, revoked bool, err error)

Logout deletes the tokens of the sign-in, keeping its organisation for the next login, and revokes the sign-in at the platform (RFC 7009). It deletes them even when the platform cannot revoke them, and then returns revoked false. signedIn is false when there was no sign-in.

func (*Client) Logs

func (c *Client) Logs(ctx context.Context, q TelemetryQuery) ([]LogLine, error)

Logs returns the log lines of the app that q selects, newest first.

func (*Client) Migrations

func (c *Client) Migrations(ctx context.Context, name string) ([]migrate.Step, error)

Migrations returns the steps of the migrations that the app name published, in order, as the platform applies them when a release rolls out. An app the platform does not have has none. Another builder's app is E-PUB-005. Every step must be numbered in order, come from a publish and hold the hash of its statement. Without a sign-in kept for the platform, or when the credentials file cannot be read, it asks nothing, takes no lock and returns E-CLI-004; a credentials file that others can read is E-CLI-007.

func (*Client) PreviewEnd

func (c *Client) PreviewEnd(ctx context.Context, app string) error

PreviewEnd ends the preview of the app on the platform, which then deletes its data. When no preview of the app runs, it says so. An app the platform does not know is E-PUB-019, and one the builder does not own E-PUB-005, as the platform's answer says.

func (*Client) PreviewStart

func (c *Client) PreviewStart(ctx context.Context, id string) (Preview, error)

PreviewStart runs the publish id as its app's preview on the platform, in place of the version the preview runs, and returns the preview. A publish that has not passed its checks is E-REL-029, and one whose permission list declares values not set for the preview E-REL-030; an id the platform does not know is E-PUB-013, and a publish of an app the builder does not own E-PUB-005, as the platform's answer says.

func (*Client) Publish

func (c *Client) Publish(ctx context.Context, id string) (Publish, error)

Publish returns the publish id, which must match PublishID. It reads an answer of up to 8 MiB, since a publish may have many problems. An id the platform does not know is E-PUB-013, and a publish of an app the builder does not own E-PUB-005, as the platform's answer says.

func (*Client) Refresh

func (c *Client) Refresh(ctx context.Context, stale string) (string, error)

Refresh refreshes the sign-in at once, as Token does when it expires, and returns its new access token. stale is the access token the platform refused for want of a scope: when another command has refreshed the sign-in since, Refresh returns the new token as it is. A refresh brings the scopes of the apps the builder owns now, such as the app its first publish created.

func (*Client) Release added in v0.13.0

func (c *Client) Release(ctx context.Context, id string) (Publish, error)

Release asks the platform to release the publish id, which is held for its preview, and returns the publish after the request: the platform decides again against the app's type, and the publish goes live by itself, waits for an approver, or is refused. A request made again returns the publish as it is. A publish that is not held, as one published with release or one that has not passed its checks, is E-REL-037, and one that a newer publish of the app superseded E-REL-038; an id the platform does not know is E-PUB-013, and a publish of an app the builder does not own E-PUB-005, as the platform's answer says.

func (*Client) RunningPreview added in v0.13.0

func (c *Client) RunningPreview(ctx context.Context, app string) (Preview, bool, error)

RunningPreview returns the preview of the app on the platform, and whether one runs. Its Reset is false. An app the platform does not know is E-PUB-019, and one the builder does not own E-PUB-005, as the platform's answer says.

func (*Client) Spans

func (c *Client) Spans(ctx context.Context, q TelemetryQuery) ([]Span, error)

Spans returns the spans of the app that q selects, newest first. It takes no Level or Trace.

func (*Client) Token

func (c *Client) Token(ctx context.Context) (string, error)

Token returns the access token of the sign-in to the platform, refreshed first when it expires within 30 seconds. It holds the lock on the credentials file meanwhile, so that of the aicoded commands that run at once only one refreshes the sign-in, and the others use its new token. Without a sign-in it is E-CLI-004. When the platform no longer refreshes the sign-in, Token deletes its tokens, keeps its organisation, and returns E-CLI-004 too. When the platform cannot refresh it right now, Token keeps it and returns E-CLI-009.

func (*Client) Trace

func (c *Client) Trace(ctx context.Context, q TelemetryQuery) ([]Span, error)

Trace returns the spans of the trace q.Trace of the app, newest first: at most q.Limit, or 1000 when it is 0. It takes no Level.

func (*Client) Whoami

func (c *Client) Whoami(ctx context.Context) (Whoami, error)

Whoami asks the platform who the sign-in is for, after refreshing it when needed.

type Created

type Created struct {
	ID         string
	CreatedApp bool
}

Created is the platform's answer to an upload.

type Credentials

type Credentials struct {
	Org          string    `json:"org"`
	AccessToken  string    `json:"access_token,omitempty"`
	RefreshToken string    `json:"refresh_token,omitempty"`
	Expires      time.Time `json:"expires,omitzero"`
}

Credentials are a builder's sign-in at one platform. Without tokens they are signed out, and Org is the organisation to sign in to again.

func Load

func Load(address string) (Credentials, error)

Load returns the credentials kept for the platform at address, empty when there are none. A file that others can read is E-CLI-007.

type Declined

type Declined struct {
	// By is the approver's email.
	By     string    `json:"by"`
	Reason string    `json:"reason"`
	At     time.Time `json:"at"`
}

Declined is an approver's decline of a publish's approval card.

type Last

type Last struct{ ID, SHA, Status string }

Last is an app's latest publish.

type LogLine

type LogLine struct {
	Time       time.Time         `json:"time"`
	Level      string            `json:"level"`
	Body       string            `json:"body"`
	TraceID    string            `json:"trace_id,omitempty"`
	SpanID     string            `json:"span_id,omitempty"`
	Release    string            `json:"release"`
	Env        string            `json:"env"`
	Attributes map[string]string `json:"attributes,omitempty"`
}

LogLine is a line of an app's log on the platform, with its text cleaned for a terminal.

type Parent

type Parent struct {
	ID  string `json:"id"`
	SHA string `json:"sha"`
}

Parent is the publish before another.

type Preview

type Preview struct {
	App     string    `json:"app"`
	Host    string    `json:"host"`
	URL     string    `json:"url"`
	Publish string    `json:"publish"`
	Started time.Time `json:"started"`
	Expires time.Time `json:"expires"`
	Reset   bool      `json:"reset"`
}

Preview is the preview of an app on the platform: the publish it runs, at Host, which URL opens, from Started until Expires. Reset is whether this start deleted the preview's data, since the publish it ran had schema changes that this one does not continue.

type Publish

type Publish struct {
	ID      string `json:"id"`
	App     string `json:"app"`
	SHA     string `json:"sha"`
	Summary string `json:"summary"`
	// Status is queued, running, passed, failed, refused or error.
	Status string `json:"status"`
	// Reason says why the publish was refused or ended in error.
	Reason  string    `json:"reason,omitempty"`
	Created time.Time `json:"created"`
	Ended   time.Time `json:"ended,omitzero"`
	// Parent is the publish whose history this one's bundle continues.
	Parent           *Parent `json:"parent,omitempty"`
	HistoryRewritten bool    `json:"history_rewritten"`
	// Checks is "all" when every security check ran, the simulated attacks (L7) included,
	// "all-but-l7" when every one but the simulated attacks ran, and "partial" when some of them
	// did not.
	Checks   string            `json:"checks"`
	Steps    []Step            `json:"steps"`
	Problems []problem.Problem `json:"problems"`
	// Notes are findings in the shape of problems that do not stop the publish. A platform that
	// sends none leaves them empty.
	Notes []problem.Problem `json:"notes"`
	// Record is the number of the publish's change record, once it is written.
	Record int64 `json:"record,omitempty"`
	// Release is the platform's decision on releasing a publish that passed, once it is made.
	Release *Release `json:"release,omitempty"`
	// Declined is the decline of the publish's approval card, which is final, or nil.
	Declined *Declined `json:"declined,omitempty"`
}

Publish is a publish as the platform reports it, with its text cleaned for a terminal.

func (Publish) Done

func (p Publish) Done() bool

Done reports whether the publish has ended.

type Release

type Release struct {
	// Tier is R1 (Pre-approved), R2 (Needs approval) or R3 (Not allowed).
	Tier string `json:"tier"`
	// AppType is the app type that decided, as <name>@<version>, such as internal-tool@builtin.
	AppType string `json:"app_type"`
	// Reasons say why the publish needs approval, empty for R1.
	Reasons []problem.Problem `json:"reasons"`
	// State is held (held for its owner's preview until the owner asks for its release), due,
	// waiting, released, failed (its newest release failed where the app runs), replaced (its
	// release went live and a newer release has since), refused or superseded.
	State string `json:"state"`
	// Reason says why the release was refused or failed.
	Reason string `json:"reason,omitempty"`
	// Live is whether the release went live.
	Live bool `json:"live"`
	// URL is the address viewers open, https://<host>/, present while the release is live. An
	// older platform leaves it out.
	URL string `json:"url,omitempty"`
	// Replaced is the older publish of the app that this one superseded while it was waiting for
	// approval or going live, as ReplacedState says, or "".
	Replaced      string `json:"replaced,omitempty"`
	ReplacedState string `json:"replaced_state,omitempty"`
}

Release is the decision on releasing a publish to production and what became of it.

type Span

type Span struct {
	Time          time.Time         `json:"time"`
	TraceID       string            `json:"trace_id"`
	SpanID        string            `json:"span_id"`
	ParentSpanID  string            `json:"parent_span_id,omitempty"`
	Name          string            `json:"name"`
	Kind          string            `json:"kind"`
	DurationNS    int64             `json:"duration_ns"`
	Status        string            `json:"status"`
	StatusMessage string            `json:"status_message,omitempty"`
	Release       string            `json:"release"`
	Env           string            `json:"env"`
	Attributes    map[string]string `json:"attributes,omitempty"`
}

Span is a span of an app on the platform, with its text cleaned for a terminal: Time is its start, and DurationNS its length in nanoseconds.

type Step

type Step struct {
	Name    string `json:"name"`
	Outcome string `json:"outcome"`
}

Step is a step of the delivery pipeline, such as check, and its outcome: passed, failed, skipped or error.

type TelemetryQuery

type TelemetryQuery struct {
	App, Env     string
	Since, Until time.Time
	Level, Trace string
	Limit        int
}

TelemetryQuery selects what Logs, Spans and Trace read of the app App, by its name, in the environment Env, preview or production. Since and Until bound the time read: zero for the platform's own, the last hour up to now; at most 7 days apart (E-PUB-015). Limit is the most rows, at most 1000 (E-PUB-016), or 0 for 100. Level, the lowest level shown, and Trace, a trace id, keep only some log lines; Trace is the trace that Trace reads.

type Upload

type Upload struct {
	App, SHA, Summary string
	// Migration is the app's schema-change draft, .aicoded/migration.sql, or "" when it has
	// none.
	Migration string
	// Release asks for the release at once, once the publish passed, skipping its owner's
	// preview; without it the platform holds the publish for the preview until its owner asks.
	Release bool
	Bundle  []byte
}

Upload is a commit of an app to publish, with the git bundle that carries it.

type Whoami

type Whoami struct {
	Org    string   `json:"org"`
	Email  string   `json:"email"`
	Scopes []string `json:"scopes"`
}

Whoami is who a sign-in is for.

Directories

Path Synopsis
Package platformtest fakes the platform on 127.0.0.1, for the tests of aicoded: its sign-in, token, revocation and whoami endpoints, and the builder API that aicoded publish, status, logs, traces, preview and release call.
Package platformtest fakes the platform on 127.0.0.1, for the tests of aicoded: its sign-in, token, revocation and whoami endpoints, and the builder API that aicoded publish, status, logs, traces, preview and release call.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL