cloudapi

package
v0.24.0-rc.1 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: 18 Imported by: 0

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:

  1. repos.status: what is published, and the server's limits;
  2. repos.list_missing_blobs: which of the files' blob ids (repoformat.BlobID) the server lacks;
  3. repos.create_blobs: upload those, in batches within the limits;
  4. 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

View Source
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.

View Source
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"
	// CodeUnavailable: the server can't take the call now; its details say how
	// 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 IsCode

func IsCode(err error, code string) bool

IsCode reports whether err is the server's answer with code.

func IsForbidden

func IsForbidden(err error) bool

IsForbidden reports the server refusing the caller the op.

func Missing

func Missing(err error) (oids []string, ok bool)

Missing is the blob ids a blobs_missing answer names; ok is false for any other error.

func ParseAddress added in v0.20.0

func ParseAddress(raw string) (origin, slug string, err error)

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

func ParseOrigin(raw string) (string, error)

ParseOrigin canonicalizes a server origin; HTTP is allowed only on literal loopback.

Types

type BlobContent added in v0.20.0

type BlobContent struct {
	OID     string `json:"oid"`
	Content []byte `json:"content"`
}

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 NewClient

func NewClient(org Org, opts ClientOptions) *Client

NewClient is a client of org.

func (*Client) CreateBlobs

func (c *Client) CreateBlobs(ctx context.Context, blobs [][]byte) ([]string, error)

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

func (c *Client) GetBlobs(ctx context.Context, oids []string) (GetBlobsOut, error)

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

func (c *Client) ListFiles(ctx context.Context, revision string, withConfig bool) ([]File, error)

ListFiles is a revision's files, as paths and blob ids, the repo's settings file among them withConfig.

func (*Client) ListMissingBlobs

func (c *Client) ListMissingBlobs(ctx context.Context, oids []string) ([]string, error)

ListMissingBlobs is those of oids the org's repo lacks, in the order given.

func (*Client) Publish

func (c *Client) Publish(ctx context.Context, in PublishIn) (PublishOut, error)

Publish publishes in.Files as the whole of the org's repo.

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

func (c *Client) RepoConfig(ctx context.Context) (out RepoConfigOut, ok bool, err error)

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) Status

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

Status is the org's published revision, and the server's limits.

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

type CloudServer struct {
	Label  string
	Origin string
}

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

type DataSource struct {
	Name string `json:"name"`
	Type string `json:"type"`
}

DataSource is a data source as the server shows it: never its connection.

type Error

type Error struct {
	Status   int
	Response apperr.Response
}

Error is the server's answer to a call that failed: its error body, and the HTTP status.

func (*Error) Error

func (e *Error) Error() string

type File

type File struct {
	Path string `json:"path"`
	OID  string `json:"oid"`
}

File is one file to publish.

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

func (l Limits) MaxFileBytes() int

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

type Org struct {
	Origin string
	Slug   string
}

Org is one org on its canonical server origin, never a credential.

func ParseOrg

func ParseOrg(raw string) (Org, error)

ParseOrg reads the copied org address, rejecting encoded paths and unsafe origins.

func ParseOrgAddress added in v0.20.0

func ParseOrgAddress(raw string) (Org, error)

ParseOrgAddress reads an org's address a person gave, or any page's under it (ParseAddress).

func (Org) Endpoint

func (o Org) Endpoint(op string) string

Endpoint is where the server serves op for this org.

func (Org) String

func (o Org) String() string

String is the org's canonical address.

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

type RefusedSetting struct {
	Key        string `json:"key"`
	Permission string `json:"permission"`
}

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

type TestDataSourceOut struct {
	OK      bool   `json:"ok"`
	Message string `json:"message,omitempty"`
}

TestDataSourceOut is a check's outcome.

Jump to

Keyboard shortcuts

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