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
- Variables
- func Address() (string, error)
- func Delete(address string) error
- func Fix(code string) string
- func Save(address string, cr Credentials) error
- func ValidOrg(s string) bool
- func When(name, s string, now time.Time) (time.Time, error)
- type App
- type Client
- func (c *Client) App(ctx context.Context, name string) (app App, found bool, err error)
- func (c *Client) CreatePublish(ctx context.Context, u Upload) (Created, error)
- func (c *Client) Login(ctx context.Context, org string, device bool) (Whoami, error)
- func (c *Client) Logout(ctx context.Context) (signedIn, revoked bool, err error)
- func (c *Client) Logs(ctx context.Context, q TelemetryQuery) ([]LogLine, error)
- func (c *Client) Migrations(ctx context.Context, name string) ([]migrate.Step, error)
- func (c *Client) PreviewEnd(ctx context.Context, app string) error
- func (c *Client) PreviewStart(ctx context.Context, id string) (Preview, error)
- func (c *Client) Publish(ctx context.Context, id string) (Publish, error)
- func (c *Client) Refresh(ctx context.Context, stale string) (string, error)
- func (c *Client) Spans(ctx context.Context, q TelemetryQuery) ([]Span, error)
- func (c *Client) Token(ctx context.Context) (string, error)
- func (c *Client) Trace(ctx context.Context, q TelemetryQuery) ([]Span, error)
- func (c *Client) Whoami(ctx context.Context) (Whoami, error)
- type Created
- type Credentials
- type Declined
- type Last
- type LogLine
- type Parent
- type Preview
- type Publish
- type Release
- type Span
- type Step
- type TelemetryQuery
- type Upload
- type Whoami
Constants ¶
const DefaultAddress = "https://api.aicoded.cloud"
DefaultAddress is the platform's address when AICODED_PLATFORM is not set.
const MaxBundle = 32 << 20
MaxBundle is the size of the largest bundle the platform takes: 32 MiB.
const MaxRows = 1000
MaxRows is the most rows a read of logs or spans answers.
Variables ¶
var Envs = []string{"preview", "production"}
Envs are the environments of an app on the platform whose logs and traces can be read.
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.
var ErrCancelled = errors.New("sign-in cancelled")
ErrCancelled is Login's error when its context ends before the sign-in does.
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.
var ( // PublishID matches the id of a publish. PublishID = regexp.MustCompile(`^pub_[a-z2-7]{26}$`) )
var TraceID = regexp.MustCompile(`^[0-9a-f]{32}$`)
TraceID matches a trace id: 32 of 0-9 and a-f.
Functions ¶
func Address ¶
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 ¶
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 ¶
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.
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 ¶
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 ¶
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 ¶
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.
func (*Client) Login ¶
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 ¶
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) Migrations ¶
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 ¶
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 ¶
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 ¶
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 ¶
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) Spans ¶
Spans returns the spans of the app that q selects, newest first. It takes no Level or Trace.
func (*Client) Token ¶
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.
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 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 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.
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 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"`
}
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 ¶
Step is a step of the delivery pipeline, such as check, and its outcome: passed, failed, skipped or error.
type TelemetryQuery ¶
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.
Source Files
¶
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 and preview 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 and preview call. |