cloudapi

package
v0.11.0 Latest Latest
Warning

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

Go to latest
Published: Oct 19, 2026 License: Apache-2.0 Imports: 14 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.

Index

Constants

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

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

The error codes the CLI tells apart.

Variables

This section is empty.

Functions

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 Unknown added in v0.10.0

func Unknown(err error, field string) bool

Unknown reports the server refusing field of the input as one its op does not take: a server older than this client, for a field added since.

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

func (c *Client) ListDataSources(ctx context.Context) ([]DataSource, error)

ListDataSources is the org's data sources, by name and type.

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) 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 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"`
	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 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

func ParseOrg(raw string) (Org, error)

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.

func (Org) Endpoint

func (o Org) Endpoint(op string) string

Endpoint is where the server serves op for the org.

func (Org) String

func (o Org) String() string

String is the org's address.

type Person

type Person struct {
	ID    string `json:"id"`
	Email string `json:"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"`
}

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 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"`
	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