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.
Index ¶
- Constants
- func IsCode(err error, code string) bool
- func IsForbidden(err error) bool
- func Missing(err error) (oids []string, ok bool)
- 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) ListDataSources(ctx context.Context) ([]DataSource, 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) Status(ctx context.Context) (StatusOut, error)
- func (c *Client) TestDataSource(ctx context.Context, in TestDataSourceIn) (TestDataSourceOut, error)
- type ClientOptions
- type CreateBlobsIn
- type CreateBlobsOut
- type CreateDataSourceIn
- type DataSource
- type Error
- type File
- type Limits
- type ListDataSourcesOut
- type ListMissingBlobsIn
- type ListMissingBlobsOut
- type MissingBlobs
- type Org
- type Person
- type PublishIn
- type PublishOut
- type PublishSettings
- type Replaced
- type StatusOut
- type TestDataSourceIn
- type TestDataSourceOut
Constants ¶
const ( OpStatus = "repos.status" OpListMissingBlobs = "repos.list_missing_blobs" OpCreateBlobs = "repos.create_blobs" OpPublish = "repos.publish" OpListDataSources = "data_sources.list" OpCreateDataSource = "data_sources.create" OpTestDataSource = "data_sources.test" )
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" )
The error codes the CLI tells apart.
Variables ¶
This section is empty.
Functions ¶
func IsForbidden ¶
IsForbidden reports the server refusing the caller the op.
Types ¶
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) ListDataSources ¶
func (c *Client) ListDataSources(ctx context.Context) ([]DataSource, error)
ListDataSources is the org's data sources, by name and type.
func (*Client) ListMissingBlobs ¶
ListMissingBlobs is those of oids the org's repo lacks, in the order given.
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 adds the caller's credential to a request.
Authorize func(*http.Request)
// UserAgent names the client and its version, for a server to tell which
// clients still call it.
UserAgent string
}
ClientOptions are what a Client sends with every call.
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"`
}
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 Limits ¶
type Limits struct {
Files int `json:"files"`
UploadBlobs int `json:"upload_blobs"`
UploadBytes int `json:"upload_bytes"`
}
Limits are the server's bounds on publishing, which the client batches by.
type ListDataSourcesOut ¶
type ListDataSourcesOut struct {
DataSources []DataSource `json:"data_sources"`
}
ListDataSourcesOut is the org's data sources.
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 MissingBlobs ¶
type MissingBlobs struct {
OIDs []string `json:"oids"`
}
MissingBlobs are the details of blobs_missing.
type Org ¶
type Org struct {
Origin string // the server's scheme and host: https://bi.example.com
Slug string // the org's slug: acme
}
Org is where a repo publishes: an org on a server, named by its address there, https://bi.example.com/o/acme.
func ParseOrg ¶
ParseOrg reads an Org from the org's address, https://bi.example.com/o/acme: the address of the org's pages, which is what a person copies. It must be https, except on a loopback host, since a publish carries a credential.
type Person ¶
Person is who published a revision. Email is empty once the account is gone, or has left the org.
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 PublishSettings ¶
type PublishSettings struct {
Limits Limits `json:"limits"`
}
PublishSettings are how to publish to the server.
type Replaced ¶
type Replaced struct {
Revision string `json:"revision"`
PublishedBy *Person `json:"published_by,omitempty"`
PublishedAt time.Time `json:"published_at"`
}
Replaced is a published revision a publish replaced.
type StatusOut ¶
type StatusOut struct {
Revision string `json:"revision"`
PublishedBy *Person `json:"published_by,omitempty"`
PublishedAt time.Time `json:"published_at"`
Publish PublishSettings `json:"publish"`
}
StatusOut is the org's published revision, and the server's publishing limits.
type TestDataSourceIn ¶
type TestDataSourceIn struct {
Name string `json:"name,omitempty"`
Type string `json:"type,omitempty"`
Connection map[string]any `json:"connection,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.