api

package
v0.12.1 Latest Latest
Warning

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

Go to latest
Published: Jul 27, 2026 License: Apache-2.0 Imports: 22 Imported by: 0

Documentation

Overview

Package api is the HTTP client for the Volcano cloud API.

Index

Constants

View Source
const (

	// DefaultPage is the first page fetched by paginated API callers.
	DefaultPage = 1
	// DefaultLimit is the default number of resources fetched per page.
	DefaultLimit = 100
)
View Source
const (

	// CLIInstructionSuggestionVersionUpgrade signals a newer CLI is published; non-blocking.
	CLIInstructionSuggestionVersionUpgrade = "suggestion_version_upgrade"
	// CLIInstructionRequireVersionUpgrade signals this CLI version is no longer
	// supported. The API pairs it with an HTTP 426 on non-exempt routes.
	CLIInstructionRequireVersionUpgrade = "require_version_upgrade"

	// CLIInstructionLowCreditWarning and CLIInstructionNotEnoughCredit are
	// RESERVED for a future billing/credit gate. PrintAPIInstructionNotices
	// already has cases for both, but they're unreached today: the API does
	// not emit them yet — billing integration into this protocol needs its own
	// design pass. Naming is locked in now, parallel to the version
	// instructions, so a future server-side implementation doesn't need a
	// wire-format rename.
	CLIInstructionLowCreditWarning = "low_credit_warning"
	CLIInstructionNotEnoughCredit  = "not_enough_credit"

	// DeviceInstructionReauth signals the platform token needs re-authentication.
	DeviceInstructionReauth = "reauth"
)

Header names and instruction values for the CLI version protocol. This is the CLI's HTTP wire contract and is duplicated here because this repository has no shared Go module with the API. The claimed version is advisory input only and never a privilege: the CLI cannot make this request header trustworthy, and it does not use the value to grant authority.

Variables

View Source
var ErrNotFound = errors.New("not found")

ErrNotFound is returned by resolver lookups when no matching resource exists. Callers branch on it with errors.Is(err, api.ErrNotFound).

Functions

func DebugEnabled added in v0.4.0

func DebugEnabled() bool

DebugEnabled reports whether API tracing is on.

func ResetLastInstructionsForTest added in v0.1.0

func ResetLastInstructionsForTest()

ResetLastInstructionsForTest clears the process-global instructions state. Test-only: production never needs this, since each CLI invocation is a fresh process. Call it between test cases that expect LastInstructions() to start from the zero value — recordInstructions is intentionally sticky (see its doc comment): a response that omits a field never clears a previously recorded value for it, so tests must reset explicitly rather than relying on an unrelated response to clear prior state.

func SetDebug added in v0.4.0

func SetDebug(on bool)

SetDebug enables or disables API request/response tracing to stderr.

func Status

func Status(err error) int

Status returns the HTTP status code carried by an *Error wrapped in err, or 0 if err is nil or does not wrap an *Error.

func WebSignupURL added in v0.0.4

func WebSignupURL(webURL, email, next string) (string, error)

WebSignupURL builds the Volcano Web signup URL used by the CLI signup flow. next must be a same-origin relative path: Volcano Web's signup page rejects any next value that isn't (see isSafeInternalPath in volcano-web).

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is a thin wrapper around the generated OpenAPI client.

func NewClient

func NewClient(apiURL, token string, opts ...Option) (*Client, error)

NewClient constructs a generated client with auth and error-normalization helpers.

func (*Client) ApplyProjectConfig added in v0.0.5

func (c *Client) ApplyProjectConfig(ctx context.Context, projectID uuid.UUID, manifestJSON []byte, dryRun bool) (*apiclient.ProjectConfigApplyResult, error)

ApplyProjectConfig uploads a full configuration manifest (pre-encoded JSON) and returns the server's per-resource apply report.

func (*Client) CopyStorageObject

func (c *Client) CopyStorageObject(ctx context.Context, bucketName, from, to string) (*apiclient.StorageObject, error)

CopyStorageObject copies one object within a bucket.

func (*Client) CreateDatabase

func (c *Client) CreateDatabase(ctx context.Context, projectID uuid.UUID, name, region, pgVersion, databaseType string) (*apiclient.Database, error)

CreateDatabase creates a database in a project.

func (*Client) CreateFrontendCustomDomain

func (c *Client) CreateFrontendCustomDomain(ctx context.Context, projectID, frontendID uuid.UUID, input FrontendCustomDomainInput) (*apiclient.FrontendCustomDomainResponse, error)

CreateFrontendCustomDomain attaches a BYOC custom domain to a frontend.

func (*Client) CreateFunctionScheduler

func (c *Client) CreateFunctionScheduler(ctx context.Context, projectID, functionID uuid.UUID, input FunctionSchedulerInput) (*apiclient.FunctionScheduler, error)

CreateFunctionScheduler creates one scheduler for a function.

func (*Client) CreateProject

func (c *Client) CreateProject(ctx context.Context, name string) (*apiclient.Project, error)

CreateProject creates a project for the authenticated user.

func (*Client) CreateServiceKey added in v0.0.4

func (c *Client) CreateServiceKey(ctx context.Context, projectID uuid.UUID, name string, permissions []string) (*apiclient.ServiceKey, error)

CreateServiceKey creates one service key in a project. When permissions is non-empty the key is scoped to exactly those operations; otherwise the server grants full access (["*"]).

func (*Client) CreateStorageBucket

func (c *Client) CreateStorageBucket(ctx context.Context, projectID uuid.UUID, input StorageBucketCreateInput) (*apiclient.StorageBucket, error)

CreateStorageBucket creates one bucket in the project.

func (*Client) CreateStoragePolicy

func (c *Client) CreateStoragePolicy(ctx context.Context, projectID uuid.UUID, bucketName string, input StoragePolicyCreateInput) (*apiclient.StoragePolicy, error)

CreateStoragePolicy attaches a new policy to a bucket.

func (*Client) CreateVariable

func (c *Client) CreateVariable(ctx context.Context, projectID uuid.UUID, name, value string) (*apiclient.Variable, error)

CreateVariable creates a variable in a project.

func (*Client) DeleteDatabase

func (c *Client) DeleteDatabase(ctx context.Context, projectID uuid.UUID, databaseName string) error

DeleteDatabase deletes one database by name.

func (*Client) DeleteFrontend

func (c *Client) DeleteFrontend(ctx context.Context, projectID, frontendID uuid.UUID) error

DeleteFrontend starts deleting one frontend by ID.

func (*Client) DeleteFrontendCustomDomain

func (c *Client) DeleteFrontendCustomDomain(ctx context.Context, projectID, frontendID uuid.UUID) error

DeleteFrontendCustomDomain detaches the configured custom domain from a frontend.

func (*Client) DeleteFunction

func (c *Client) DeleteFunction(ctx context.Context, projectID, functionID uuid.UUID) error

DeleteFunction starts deleting one function by ID.

func (*Client) DeleteFunctionScheduler

func (c *Client) DeleteFunctionScheduler(ctx context.Context, projectID, functionID, schedulerID uuid.UUID) error

DeleteFunctionScheduler deletes one scheduler for a function.

func (*Client) DeleteProject

func (c *Client) DeleteProject(ctx context.Context, projectID uuid.UUID) error

DeleteProject starts project deletion.

func (*Client) DeleteStorageBucket

func (c *Client) DeleteStorageBucket(ctx context.Context, projectID uuid.UUID, bucketName string) error

DeleteStorageBucket removes one bucket from the project.

func (*Client) DeleteStorageObject

func (c *Client) DeleteStorageObject(ctx context.Context, bucketName, path string) error

DeleteStorageObject removes one object from a bucket.

func (*Client) DeleteStoragePolicy

func (c *Client) DeleteStoragePolicy(ctx context.Context, projectID uuid.UUID, bucketName string, policyID uuid.UUID) error

DeleteStoragePolicy removes one policy from a bucket.

func (*Client) DeleteVariable

func (c *Client) DeleteVariable(ctx context.Context, projectID uuid.UUID, name string) error

DeleteVariable deletes one variable by name.

func (*Client) DeployFrontend

func (c *Client) DeployFrontend(ctx context.Context, projectID uuid.UUID, input FrontendDeployInput) (*apiclient.Frontend, error)

DeployFrontend uploads one frontend source archive.

func (*Client) DeployFunction

func (c *Client) DeployFunction(ctx context.Context, projectID uuid.UUID, fn FunctionDeployInput) (*apiclient.Function, error)

DeployFunction deploys one function source archive.

func (*Client) DeployFunctionsBatch

func (c *Client) DeployFunctionsBatch(ctx context.Context, projectID uuid.UUID, functions []FunctionDeployInput) (*apiclient.BatchFunctionDeployResponse, error)

DeployFunctionsBatch deploys one batch of function source archives.

func (*Client) DownloadStorageObject

func (c *Client) DownloadStorageObject(ctx context.Context, bucketName, path string) (*http.Response, error)

DownloadStorageObject opens a streaming download for one object. The caller is responsible for closing the response body.

func (*Client) ExchangePlatformToken

func (c *Client) ExchangePlatformToken(ctx context.Context, authAccessToken, clientID string) (*apiclient.PlatformExchangeResponse, error)

ExchangePlatformToken exchanges an auth-user device-flow token for a platform token.

func (*Client) GetDatabase

func (c *Client) GetDatabase(ctx context.Context, projectID uuid.UUID, databaseName string) (*apiclient.Database, error)

GetDatabase returns one database by name.

func (*Client) GetFrontend

func (c *Client) GetFrontend(ctx context.Context, projectID, frontendID uuid.UUID) (*apiclient.Frontend, error)

GetFrontend returns one frontend by ID.

func (*Client) GetFrontendCustomDomain

func (c *Client) GetFrontendCustomDomain(ctx context.Context, projectID, frontendID uuid.UUID) (*apiclient.FrontendCustomDomainResponse, error)

GetFrontendCustomDomain returns the configured custom domain for a frontend.

func (*Client) GetFrontendDeploymentLogs

func (c *Client) GetFrontendDeploymentLogs(ctx context.Context, projectID, frontendID, deploymentID uuid.UUID, limit int, cursor string) (*apiclient.LogSearchResponse, error)

GetFrontendDeploymentLogs returns one build log search page for a frontend deployment.

func (*Client) GetFrontendLogs

func (c *Client) GetFrontendLogs(ctx context.Context, projectID, frontendID uuid.UUID, limit int, cursor string) (*apiclient.LogSearchResponse, error)

GetFrontendLogs returns one runtime log search page for a frontend.

func (*Client) GetFunction

func (c *Client) GetFunction(ctx context.Context, projectID, functionID uuid.UUID) (*apiclient.Function, error)

GetFunction returns one function by ID.

func (*Client) GetFunctionDeploymentLogs

func (c *Client) GetFunctionDeploymentLogs(ctx context.Context, projectID, functionID, deploymentID uuid.UUID, limit int, cursor string) (*apiclient.LogSearchResponse, error)

GetFunctionDeploymentLogs returns one build log search page for a function deployment.

func (*Client) GetFunctionLogs

func (c *Client) GetFunctionLogs(ctx context.Context, projectID, functionID uuid.UUID, limit int, cursor string) (*apiclient.LogSearchResponse, error)

GetFunctionLogs returns one runtime log search page for a function.

func (*Client) GetProject

func (c *Client) GetProject(ctx context.Context, projectID uuid.UUID) (*apiclient.Project, error)

GetProject returns one project by ID.

func (*Client) GetProjectConfigYAML added in v0.0.5

func (c *Client) GetProjectConfigYAML(ctx context.Context, projectID uuid.UUID) ([]byte, error)

GetProjectConfigYAML downloads the project configuration as the canonical YAML manifest rendered by the server, returned verbatim.

func (*Client) GetServiceKey added in v0.0.4

func (c *Client) GetServiceKey(ctx context.Context, projectID, keyID uuid.UUID) (*apiclient.ServiceKey, error)

GetServiceKey returns one service key by ID.

func (*Client) GetStorageBucket

func (c *Client) GetStorageBucket(ctx context.Context, projectID uuid.UUID, bucketName string) (*apiclient.StorageBucket, error)

GetStorageBucket returns one bucket by name.

func (*Client) GetStorageStats

func (c *Client) GetStorageStats(ctx context.Context, projectID uuid.UUID) (*apiclient.StorageStats, error)

GetStorageStats returns aggregate storage statistics for a project.

func (*Client) GetVariable

func (c *Client) GetVariable(ctx context.Context, projectID uuid.UUID, name string) (*apiclient.Variable, error)

GetVariable returns one variable by name.

func (*Client) InvokeFunction added in v0.0.4

func (c *Client) InvokeFunction(ctx context.Context, functionID uuid.UUID, input FunctionInvokeInput) (*apiclient.FunctionInvocationResponse, error)

InvokeFunction invokes one function by ID.

func (*Client) ListAnonKeys added in v0.5.0

func (c *Client) ListAnonKeys(ctx context.Context, projectID uuid.UUID) ([]apiclient.AnonKey, error)

ListAnonKeys lists a project's anon keys — the publishable JWTs that go in the frontend/SDK Authorization header (the value an app build needs).

func (*Client) ListDatabases

func (c *Client) ListDatabases(ctx context.Context, projectID uuid.UUID, page, limit int) (*apiclient.PaginatedDatabases, error)

ListDatabases lists one database page for a project.

func (*Client) ListFrontendDeployments

func (c *Client) ListFrontendDeployments(ctx context.Context, projectID, frontendID uuid.UUID, page, limit int) (*apiclient.PaginatedFrontendDeployments, error)

ListFrontendDeployments lists one deployment page for a frontend.

func (*Client) ListFrontends

func (c *Client) ListFrontends(ctx context.Context, projectID uuid.UUID, page, limit int) (*apiclient.PaginatedFrontends, error)

ListFrontends lists one frontend page for a project.

func (*Client) ListFunctionDeployments

func (c *Client) ListFunctionDeployments(ctx context.Context, projectID, functionID uuid.UUID, page, limit int) (*apiclient.PaginatedFunctionDeployments, error)

ListFunctionDeployments lists one deployment page for a function.

func (*Client) ListFunctionRuntimes

func (c *Client) ListFunctionRuntimes(ctx context.Context) ([]apiclient.FunctionRuntimeOption, error)

ListFunctionRuntimes returns the function runtime catalog.

func (*Client) ListFunctionSchedulers

func (c *Client) ListFunctionSchedulers(ctx context.Context, projectID, functionID uuid.UUID) (*apiclient.FunctionSchedulerListResponse, error)

ListFunctionSchedulers lists schedulers for a function.

func (*Client) ListFunctions

func (c *Client) ListFunctions(ctx context.Context, projectID uuid.UUID, page, limit int) (*apiclient.PaginatedFunctions, error)

ListFunctions lists one function page for a project.

func (*Client) ListProjects

func (c *Client) ListProjects(ctx context.Context, page, limit int) (*apiclient.PaginatedProjects, error)

ListProjects lists one project page for the authenticated user.

func (*Client) ListServiceKeys added in v0.0.4

func (c *Client) ListServiceKeys(ctx context.Context, projectID uuid.UUID, page, limit int) (*apiclient.PaginatedServiceKeys, error)

ListServiceKeys returns one service-key page for a project.

func (*Client) ListStorageBuckets

func (c *Client) ListStorageBuckets(ctx context.Context, projectID uuid.UUID) ([]apiclient.StorageBucket, error)

ListStorageBuckets returns every bucket in the project.

func (*Client) ListStorageObjects

func (c *Client) ListStorageObjects(ctx context.Context, bucketName string, opts StorageObjectListOptions) (*apiclient.StorageListResponse, error)

ListStorageObjects returns one cursor page of objects in a bucket.

func (*Client) ListStoragePolicies

func (c *Client) ListStoragePolicies(ctx context.Context, projectID uuid.UUID, bucketName string) ([]apiclient.StoragePolicy, error)

ListStoragePolicies returns every policy attached to a bucket.

func (*Client) ListVariables

func (c *Client) ListVariables(ctx context.Context, projectID uuid.UUID, page, limit int) (*apiclient.PaginatedVariables, error)

ListVariables lists one variable page for a project.

func (*Client) MoveStorageObject

func (c *Client) MoveStorageObject(ctx context.Context, bucketName, from, to string) (*apiclient.StorageObject, error)

MoveStorageObject renames one object within a bucket.

func (*Client) PollDeviceToken

func (c *Client) PollDeviceToken(ctx context.Context, clientID, deviceCode string) (*DeviceTokenPollResult, error)

PollDeviceToken polls the OAuth device token endpoint once.

func (*Client) RedeployFrontend

func (c *Client) RedeployFrontend(ctx context.Context, projectID, frontendID uuid.UUID) (*apiclient.Frontend, error)

RedeployFrontend starts a new deployment using the last uploaded archive.

func (*Client) SetStorageObjectVisibility

func (c *Client) SetStorageObjectVisibility(ctx context.Context, bucketName, path string, isPublic bool) (*apiclient.StorageObject, error)

SetStorageObjectVisibility updates the public/private flag for one object.

func (*Client) StartDeviceAuthorization

func (c *Client) StartDeviceAuthorization(ctx context.Context, clientID string) (*apiclient.DeviceAuthorizationResponse, error)

StartDeviceAuthorization starts the OAuth device authorization flow.

func (*Client) StreamFrontendDeploymentLogs added in v0.0.4

func (c *Client) StreamFrontendDeploymentLogs(ctx context.Context, projectID, frontendID, deploymentID uuid.UUID, limit int, lastEventID string) (*ProjectLogStream, error)

StreamFrontendDeploymentLogs opens a build log stream for a frontend deployment.

func (*Client) StreamFrontendLogs added in v0.0.4

func (c *Client) StreamFrontendLogs(ctx context.Context, projectID, frontendID uuid.UUID, limit int, lastEventID string) (*ProjectLogStream, error)

StreamFrontendLogs opens a runtime log stream for a frontend.

func (*Client) StreamFunctionDeploymentLogs added in v0.0.4

func (c *Client) StreamFunctionDeploymentLogs(ctx context.Context, projectID, functionID, deploymentID uuid.UUID, limit int, lastEventID string) (*ProjectLogStream, error)

StreamFunctionDeploymentLogs opens a build log stream for a function deployment.

func (*Client) StreamFunctionLogs added in v0.0.4

func (c *Client) StreamFunctionLogs(ctx context.Context, projectID, functionID uuid.UUID, limit int, lastEventID string) (*ProjectLogStream, error)

StreamFunctionLogs opens a runtime log stream for a function.

func (*Client) UpdateFunctionScheduler

func (c *Client) UpdateFunctionScheduler(ctx context.Context, projectID, functionID, schedulerID uuid.UUID, input FunctionSchedulerInput) (*apiclient.FunctionScheduler, error)

UpdateFunctionScheduler updates one scheduler for a function.

func (*Client) UpdateFunctionVisibility

func (c *Client) UpdateFunctionVisibility(ctx context.Context, projectID, functionID uuid.UUID, isPublic bool) (*apiclient.Function, error)

UpdateFunctionVisibility updates one function's public/private visibility.

func (*Client) UpdateStorageBucket

func (c *Client) UpdateStorageBucket(ctx context.Context, projectID uuid.UUID, bucketName string, input StorageBucketUpdateInput) (*apiclient.StorageBucket, error)

UpdateStorageBucket updates one bucket's configuration.

func (*Client) UpdateVariable

func (c *Client) UpdateVariable(ctx context.Context, projectID uuid.UUID, name, value string) (*apiclient.Variable, error)

UpdateVariable updates one variable by name.

func (*Client) UploadStorageObject

func (c *Client) UploadStorageObject(ctx context.Context, bucketName, path, contentType string, content io.Reader) (*apiclient.StorageObject, error)

UploadStorageObject uploads one object to a bucket via a streaming multipart request. The body is assembled lazily through an io.Pipe so the caller's reader is consumed in fixed-size chunks rather than buffered in memory.

func (*Client) ValidateToken

func (c *Client) ValidateToken(ctx context.Context) error

ValidateToken validates the configured token by listing projects.

type DeviceTokenPollResult

type DeviceTokenPollResult struct {
	AccessToken      string
	Error            string
	ErrorDescription string
}

DeviceTokenPollResult is the normalized result of a device-token poll.

type Error

type Error struct {
	StatusCode int
	Message    string
}

Error is a normalized error returned for non-successful API responses.

func (*Error) Error

func (e *Error) Error() string

type FrontendCustomDomainInput

type FrontendCustomDomainInput struct {
	Domain              string
	CertificatePEM      string
	PrivateKeyPEM       string
	CertificateChainPEM string
}

FrontendCustomDomainInput contains one custom domain attach request.

type FrontendDeployInput

type FrontendDeployInput struct {
	Name      string
	Framework string
	AppRoot   string
	Archive   []byte
}

FrontendDeployInput contains one packaged frontend source archive.

type FunctionDeployInput

type FunctionDeployInput struct {
	Name          string
	Runtime       string
	Handler       string
	SourceArchive []byte
}

FunctionDeployInput contains one packaged function source archive.

type FunctionInvokeInput added in v0.0.4

type FunctionInvokeInput struct {
	Payload map[string]any
}

FunctionInvokeInput contains one function invocation request.

type FunctionSchedulerInput

type FunctionSchedulerInput struct {
	Name           string
	CronExpression string
	Payload        map[string]any
	Regions        []string
	Enabled        *bool
}

FunctionSchedulerInput contains one function scheduler create or update request.

type Instructions added in v0.1.0

type Instructions struct {
	CLIInstruction    string
	LatestVersion     string
	DeviceInstruction string
}

Instructions is a snapshot of the most recent VOL-180 protocol signals observed on any API response in this process.

func ConsumeCLIInstructions added in v0.1.0

func ConsumeCLIInstructions() Instructions

ConsumeCLIInstructions returns each observed CLI instruction/latest-version pair once. Repeated API responses commonly carry the same pair, so retaining the last consumed pair prevents a long-running command from rendering the same notice again after a poll or stream reconnect. DeviceInstruction is returned unchanged because callers render the reauthentication hint from LastInstructions alongside command errors.

func LastInstructions added in v0.1.0

func LastInstructions() Instructions

LastInstructions returns the most recently observed VOL-180 instructions from any API response in this process. It retains the latest observed values after ConsumeCLIInstructions renders their one-shot notice so error paths can still use response metadata such as LatestVersion. It is the zero value if no API call has completed yet — e.g. local-only commands (init, help, version, completion) never populate this, since they never make a request.

A CLI process runs exactly one command per invocation, so "most recent" is simply "from the request(s) this command made" — there is no cross-command state to reconcile.

type Option

type Option func(*options)

Option configures a cloud API client.

func WithHTTPClient

func WithHTTPClient(httpClient apiclient.HttpRequestDoer) Option

WithHTTPClient injects the HTTP client used by the generated API client.

type ProjectConfigValidationError added in v0.0.5

type ProjectConfigValidationError struct {
	Errors []apiclient.ProjectConfigValidationError
}

ProjectConfigValidationError is returned when the server rejects a config manifest with 422. Nothing was applied; Errors carries the full list.

func (*ProjectConfigValidationError) Error added in v0.0.5

type ProjectLogStream added in v0.0.4

type ProjectLogStream struct {
	// contains filtered or unexported fields
}

ProjectLogStream reads project log Server-Sent Events.

func (*ProjectLogStream) Close added in v0.0.4

func (s *ProjectLogStream) Close() error

Close closes the underlying response body.

func (*ProjectLogStream) Next added in v0.0.4

Next returns the next non-comment SSE event.

type ProjectLogStreamEvent added in v0.0.4

type ProjectLogStreamEvent struct {
	ID      string
	Type    string
	Data    string
	Log     *apiclient.LogSearchEvent
	Warning string
}

ProjectLogStreamEvent is one parsed project log stream event.

type StorageBucketCreateInput

type StorageBucketCreateInput struct {
	Name             string
	AllowedMimeTypes []string
	FileSizeLimit    *int64
}

StorageBucketCreateInput captures fields supported by bucket creation.

type StorageBucketUpdateInput

type StorageBucketUpdateInput struct {
	AllowedMimeTypes *[]string
	FileSizeLimit    *int64
}

StorageBucketUpdateInput captures fields supported by bucket update.

type StorageObjectListOptions

type StorageObjectListOptions struct {
	Prefix string
	Limit  int
	Cursor string
}

StorageObjectListOptions controls the object list query.

type StoragePolicyCreateInput

type StoragePolicyCreateInput struct {
	Name       string
	Definition string
	Operation  apiclient.CreateStoragePolicyRequestOperation
}

StoragePolicyCreateInput captures fields supported by policy creation.

Jump to

Keyboard shortcuts

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