Documentation
¶
Overview ¶
Package cloudapi is the anfra CLI's client of anfra-cloud: the ops `anfra publish` calls, with types written here for them.
The contract is the server's: anfra-cloud owns its API and publishes it as api/openapi.yaml. This package vendors that file (openapi.yaml, copied by hand for now with scripts/cloudapi.sh) and a test holds these types to it, so a change on either side that the CLI would not survive fails here. The CLI calls public ops only, which anfra-cloud changes additively; a client ignores members it does not know.
A repo publishes to an org, named by its address on its server, https://bi.example.com/o/acme (Org); the server serves the org's ops at <origin>/api/o/<org>/<op>. The address is what `anfra publish --set-org` records (org.url in a repo's .anfra/config.yml). A publish is:
- repos.status: what is published, and the server's limits;
- repos.list_missing_blobs: which of the files' blob ids (repoformat.BlobID) the server lacks;
- repos.create_blobs: upload those, in batches within the limits;
- repos.publish: publish every file, by path and blob id, as the whole repo.
Before it, `anfra publish` may add the data sources the repo uses and the org lacks (data_sources.list, data_sources.test, data_sources.create), when the person agrees: a connection is never sent unasked. It also reads the origins the org's Data Apps may load from (app_origins.list), to say which of the repo's own the org does not allow.
Index ¶
- Constants
- func FormatCloudServers(servers []CloudServer) string
- func IsCode(err error, code string) bool
- func IsForbidden(err error) bool
- func Missing(err error) (oids []string, ok bool)
- func ParseAddress(raw string) (origin, slug string, err error)
- func ParseOrigin(raw string) (string, error)
- type BlobContent
- type Client
- func (c *Client) CreateBlobs(ctx context.Context, blobs [][]byte) ([]string, error)
- func (c *Client) CreateDataSource(ctx context.Context, in CreateDataSourceIn) (DataSource, error)
- func (c *Client) GetBlobs(ctx context.Context, oids []string) (GetBlobsOut, error)
- func (c *Client) ListDataSources(ctx context.Context) ([]DataSource, error)
- func (c *Client) ListFiles(ctx context.Context, revision string, withConfig bool) ([]File, error)
- func (c *Client) ListMissingBlobs(ctx context.Context, oids []string) ([]string, error)
- func (c *Client) Publish(ctx context.Context, in PublishIn) (PublishOut, error)
- func (c *Client) ReadBlobs(ctx context.Context, oids []string, limits Limits) (map[string][]byte, error)
- func (c *Client) RepoConfig(ctx context.Context) (out RepoConfigOut, ok bool, err error)
- func (c *Client) Status(ctx context.Context) (StatusOut, error)
- func (c *Client) TestDataSource(ctx context.Context, in TestDataSourceIn) (TestDataSourceOut, error)
- type ClientOptions
- type CloudServer
- type CreateBlobsIn
- type CreateBlobsOut
- type CreateDataSourceIn
- type DataSource
- type Error
- type File
- type GetBlobsIn
- type GetBlobsOut
- type Limits
- type ListDataSourcesOut
- type ListFilesIn
- type ListFilesOut
- type ListMissingBlobsIn
- type ListMissingBlobsOut
- type LiveRevision
- type MissingBlobs
- type Org
- type Person
- type PublishIn
- type PublishOut
- type RefusedSetting
- type RefusedSettings
- type Replaced
- type RepoConfigOut
- type RepoOverride
- type RepoSetting
- type RetryAfter
- type StatusOut
- type TestDataSourceIn
- type TestDataSourceOut
Constants ¶
const ( OpStatus = "repos.status" OpListMissingBlobs = "repos.list_missing_blobs" OpCreateBlobs = "repos.create_blobs" OpPublish = "repos.publish" OpListFiles = "repos.list_files" OpGetBlobs = "repos.get_blobs" OpListDataSources = "data_sources.list" OpCreateDataSource = "data_sources.create" OpTestDataSource = "data_sources.test" OpRepoConfig = "repo_config.get" )
The ops the CLI calls, by name: the contract's operationIds.
const ( // CodeRepoInvalid: a publish whose files fail the engine's validation; nothing // is published. CodeRepoInvalid = "repo_invalid" // CodeBlobsMissing: a publish naming content the server does not have; its // details are MissingBlobs. The client uploads it and publishes again. CodeBlobsMissing = "blobs_missing" // CodeForbidden: the caller lacks the permission the op needs. CodeForbidden = "forbidden" // CodeInvalidRequest: an input the op's schema refuses; its details are // apperr.Violations. CodeInvalidRequest = "invalid_request" // CodeBaseOutdated: a publish whose base is no longer the published // revision; its details are the published revision (LiveRevision). CodeBaseOutdated = "base_outdated" // CodeSettingsChangeForbidden: a publish changing repo settings in // .anfra/config.yml the caller may not change; its details name them // (RefusedSettings). Nothing is published. CodeSettingsChangeForbidden = "settings_change_forbidden" // CodeNotFound: no such thing, or, for an op, an older server without it. CodeNotFound = "not_found" // CodeRateLimited: too many calls; its details say how long to wait // (RetryAfter). CodeRateLimited = "rate_limited" // long to wait when the server knows (RetryAfter). CodeUnavailable = "unavailable" )
The error codes the CLI tells apart.
Variables ¶
This section is empty.
Functions ¶
func FormatCloudServers ¶ added in v0.21.0
func FormatCloudServers(servers []CloudServer) string
FormatCloudServers writes servers in the format ParseCloudServers reads, with each address in its canonical form.
func IsForbidden ¶
IsForbidden reports the server refusing the caller the op.
func Missing ¶
Missing is the blob ids a blobs_missing answer names; ok is false for any other error.
func ParseAddress ¶ added in v0.20.0
ParseAddress reads an address a person gave: an org's, any page under it, or only its server's. It returns the server's origin, and the org's slug when the address names one, or "". What follows the org in the address, its path, query and fragment, is dropped unread: a page's address copied from a browser works. Addresses anfra keeps, or a server returns, are parsed with ParseOrg, which allows only the org's own.
An org named by its host, such as https://acme.anfra.ai, would need asking its server: here it reads as a server's address.
func ParseOrigin ¶ added in v0.12.0
ParseOrigin canonicalizes a server origin; HTTP is allowed only on literal loopback.
Types ¶
type BlobContent ¶ added in v0.20.0
BlobContent is one blob's content.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client calls the ops `anfra publish` uses on one org: one call each, which the caller batches within the server's Limits.
func (*Client) CreateBlobs ¶
CreateBlobs uploads blobs and returns their ids, in order.
func (*Client) CreateDataSource ¶
func (c *Client) CreateDataSource(ctx context.Context, in CreateDataSourceIn) (DataSource, error)
CreateDataSource adds a data source to the org, its connection sent to be kept sealed.
func (*Client) GetBlobs ¶ added in v0.20.0
GetBlobs reads blobs' content: one call, within limits.DownloadBlobs. An answer past limits.DownloadBytes leaves some out, in Omitted.
func (*Client) ListDataSources ¶
func (c *Client) ListDataSources(ctx context.Context) ([]DataSource, error)
ListDataSources is the org's data sources, by name and type.
func (*Client) ListFiles ¶ added in v0.20.0
ListFiles is a revision's files, as paths and blob ids, the repo's settings file among them withConfig.
func (*Client) ListMissingBlobs ¶
ListMissingBlobs is those of oids the org's repo lacks, in the order given.
func (*Client) ReadBlobs ¶ added in v0.20.0
func (c *Client) ReadBlobs(ctx context.Context, oids []string, limits Limits) (map[string][]byte, error)
ReadBlobs reads every blob in oids, in calls within limits, asking again for what an answer left out.
func (*Client) RepoConfig ¶ added in v0.22.0
RepoConfig is the org's repo settings, as they apply on it. ok is false when the org's server predates them: it has no repo_config.get, so it doesn't publish the repo's settings file either.
TEMPORARY (anfra-cloud's docs/implementation/repo-config.md, Temporary checks): ok goes once no supported server lacks the op.
func (*Client) TestDataSource ¶
func (c *Client) TestDataSource(ctx context.Context, in TestDataSourceIn) (TestDataSourceOut, error)
TestDataSource checks the server can connect to a data source.
type ClientOptions ¶
type ClientOptions struct {
// HTTP is the client to send with; nil means http.DefaultClient.
HTTP *http.Client
// Authorize resolves current credentials immediately before each request.
// An error prevents dispatch; authentication failures are never retried.
Authorize func(*http.Request) error
// UserAgent names the client and its version, for a server to tell which
// clients still call it.
UserAgent string
// Waiting is told before a call waits to be tried again, after the server
// asked it to (rate_limited, unavailable), so a person can see why nothing
// moves. nil says nothing.
Waiting func(op string, wait time.Duration)
// Logger records each retry (cloudapi.retry), for a caller who sees no
// progress, such as an agent. nil records nothing.
Logger *slog.Logger
}
ClientOptions are what a Client sends with every call.
type CloudServer ¶ added in v0.21.0
CloudServer is one server bare `anfra auth login` offers. An empty Origin means the server isn't available yet, so login shows it but can't use it.
func ParseCloudServers ¶ added in v0.21.0
func ParseCloudServers(raw string) ([]CloudServer, error)
ParseCloudServers reads the list of servers ANFRA_CLOUD_URL and the build's default hold. Entries are separated by ";", and each is one of:
United States=https://us.anfra.ai a server with a label Europe a server that isn't available yet https://us.anfra.ai a server without a label
A list may be empty, or have only servers that aren't available yet. Login then offers just organization URL entry.
type CreateBlobsIn ¶
type CreateBlobsIn struct {
Blobs [][]byte `json:"blobs"`
}
CreateBlobsIn is content to store.
type CreateBlobsOut ¶
type CreateBlobsOut struct {
OIDs []string `json:"oids"`
}
CreateBlobsOut is the stored content's blob ids, in order.
type CreateDataSourceIn ¶
type CreateDataSourceIn struct {
Name string `json:"name"`
Type string `json:"type"`
Connection map[string]any `json:"connection"`
Settings map[string]any `json:"settings,omitempty"`
}
CreateDataSourceIn is a new data source.
type DataSource ¶
DataSource is a data source as the server shows it: never its connection.
type Error ¶
Error is the server's answer to a call that failed: its error body, and the HTTP status.
type GetBlobsIn ¶ added in v0.20.0
type GetBlobsIn struct {
OIDs []string `json:"oids"`
}
GetBlobsIn is blob ids to read.
type GetBlobsOut ¶ added in v0.20.0
type GetBlobsOut struct {
Blobs []BlobContent `json:"blobs"`
Omitted []string `json:"omitted"`
}
GetBlobsOut is the blobs' content, in the order named, and the ids that didn't fit in this answer, to ask again for.
type Limits ¶
type Limits struct {
Files int `json:"files"`
UploadBlobs int `json:"upload_blobs"`
UploadBytes int `json:"upload_bytes"`
// FileBytes is the largest file; a server that does not send it takes any
// file that fits in one upload call.
FileBytes int `json:"file_bytes"`
// DownloadBlobs is the most blob ids one repos.get_blobs call names.
DownloadBlobs int `json:"download_blobs"`
// DownloadBytes is the most content one repos.get_blobs answer carries:
// past it, the answer leaves the rest out, to ask again for.
DownloadBytes int `json:"download_bytes"`
}
Limits are the server's bounds on the repo ops, which the client batches by.
func (Limits) MaxFileBytes ¶ added in v0.13.5
MaxFileBytes is the largest file the server takes.
type ListDataSourcesOut ¶
type ListDataSourcesOut struct {
DataSources []DataSource `json:"data_sources"`
}
ListDataSourcesOut is the org's data sources.
type ListFilesIn ¶ added in v0.20.0
type ListFilesIn struct {
Revision string `json:"revision"`
// WithConfig lists the repo's settings file with its other files.
WithConfig bool `json:"with_config,omitempty"`
}
ListFilesIn names a revision of the org's repo.
type ListFilesOut ¶ added in v0.20.0
type ListFilesOut struct {
Files []File `json:"files"`
}
ListFilesOut is a revision's files, as a publish carries them, by path.
type ListMissingBlobsIn ¶
type ListMissingBlobsIn struct {
OIDs []string `json:"oids"`
}
ListMissingBlobsIn is blob ids the client computed from its files.
type ListMissingBlobsOut ¶
type ListMissingBlobsOut struct {
OIDs []string `json:"oids"`
}
ListMissingBlobsOut is those the server lacks, in the order given.
type LiveRevision ¶ added in v0.20.0
type LiveRevision struct {
Revision string `json:"revision"`
PublishedBy *Person `json:"published_by,omitempty"`
PublishedAt time.Time `json:"published_at"`
}
LiveRevision are the details of base_outdated: the revision published since the publish's base, to pull.
func Outdated ¶ added in v0.20.0
func Outdated(err error) (live LiveRevision, ok bool)
Outdated is the revision a base_outdated answer names, published since the publish's base; ok is false for any other error.
type MissingBlobs ¶
type MissingBlobs struct {
OIDs []string `json:"oids"`
}
MissingBlobs are the details of blobs_missing.
type Org ¶
Org is one org on its canonical server origin, never a credential.
func ParseOrgAddress ¶ added in v0.20.0
ParseOrgAddress reads an org's address a person gave, or any page's under it (ParseAddress).
type Person ¶
type Person struct {
ID string `json:"id" doc:"the person's id"`
Email string `json:"email" doc:"the person's email"`
}
Person is who published a revision. Email is empty once the account is gone, or has left the org.
type PublishIn ¶
type PublishIn struct {
Files []File `json:"files"`
Message string `json:"message,omitempty"`
// Base is the revision the files were built on: the one last pulled or
// published. When it's no longer the published revision, the server
// refuses with base_outdated. Empty, the publish replaces whatever is
// published.
Base string `json:"base,omitempty"`
// WithConfig says Files hold the repo's settings, .anfra/config.yml: a
// file not listed is deleted, the settings too. Without it, the server
// refuses the settings file, and keeps the one published. Sent to a server
// that has repo_config.get (Client.RepoConfig).
WithConfig bool `json:"with_config,omitempty"`
}
PublishIn is the files to publish, as the whole repo.
type PublishOut ¶
type PublishOut struct {
Revision string `json:"revision"`
Changed bool `json:"changed"`
Replaced *Replaced `json:"replaced,omitempty"`
}
PublishOut is a publish's outcome.
type RefusedSetting ¶ added in v0.22.0
RefusedSetting is one setting a publish may not change.
type RefusedSettings ¶ added in v0.22.0
type RefusedSettings struct {
Settings []RefusedSetting `json:"settings"`
}
RefusedSettings are a settings_change_forbidden's details.
type Replaced ¶
type Replaced struct {
Revision string `json:"revision" doc:"the revision replaced"`
PublishedBy *Person `json:"published_by,omitempty" doc:"who published it"`
PublishedAt time.Time `json:"published_at" doc:"when it was published" pretty:",moment"`
}
Replaced is a published revision a publish replaced.
type RepoConfigOut ¶ added in v0.22.0
type RepoConfigOut struct {
Settings []RepoSetting `json:"settings"`
// Revision is the published revision the repo's values come from.
Revision string `json:"revision,omitempty"`
// Error is why the settings in effect can't be used, if they can't.
Error string `json:"error,omitempty"`
}
RepoConfigOut is the org's repo settings, as they apply on it: the published .anfra/config.yml's, and an Admin's overrides.
type RepoOverride ¶ added in v0.22.0
type RepoOverride struct {
Value any `json:"value"`
UpdatedBy string `json:"updated_by,omitempty"`
UpdatedAt time.Time `json:"updated_at"`
}
RepoOverride is an Admin's override of a setting on the org.
type RepoSetting ¶ added in v0.22.0
type RepoSetting struct {
// Key is its path in .anfra/config.yml: query.cache.max_duration.
Key string `json:"key"`
// Value is the value in effect, absent at anfra's default.
Value any `json:"value,omitempty"`
// Source is where Value comes from: "repo", "override" or "default".
Source string `json:"source"`
// Repo is the published file's value, absent when it doesn't set it.
Repo any `json:"repo,omitempty"`
Override *RepoOverride `json:"override,omitempty"`
// Editable says whether the caller may change it.
Editable bool `json:"editable"`
}
RepoSetting is one setting, as it applies on the org.
type RetryAfter ¶ added in v0.20.0
type RetryAfter struct {
Seconds int `json:"retry_after_seconds"`
}
RetryAfter are the details of rate_limited and unavailable, when the server knows how long to wait.
type StatusOut ¶
type StatusOut struct {
Revision string `json:"revision"`
PublishedBy *Person `json:"published_by,omitempty"`
PublishedAt time.Time `json:"published_at"`
// Limits are read from the root: the server's deprecated publish.limits,
// the same values, is for CLIs from before pull.
Limits Limits `json:"limits"`
}
StatusOut is the org's published revision, and the server's limits.
type TestDataSourceIn ¶
type TestDataSourceIn struct {
Name string `json:"name,omitempty"`
Type string `json:"type,omitempty"`
Connection map[string]any `json:"connection,omitempty"`
Settings map[string]any `json:"settings,omitempty"`
}
TestDataSourceIn is a data source to check: one not yet added, by type and connection (and a name, to say in the answer).
type TestDataSourceOut ¶
TestDataSourceOut is a check's outcome.