rest

package
v2.0.0 Latest Latest
Warning

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

 Go to latest Published: Jul 13, 2026 License: AGPL-3.0 Imports: 13 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	APIVersion = 2
	APIURL     = fmt.Sprintf("https://api.squarecloud.app/v%d", APIVersion)
)
View Source 
var (
	// Square Cloud Service
	EndpointServiceStatus = func() string { return "/service/status" }

	// User
	EndpointUser          = func() string { return "/users/me" }
	EndpointUserSnapshots = func() string { return "/users/snapshots" }

	// Application
	EndpointApplication            = func() string { return "/apps" }
	EndpointApplicationListStatus  = func() string { return "/apps/status" }
	EndpointApplicationDomains     = func() string { return "/apps/domains" }
	EndpointLoadBalancers          = func() string { return "/apps/load-balancers" }
	EndpointApplicationInformation = func(appID string) string { return fmt.Sprintf("/apps/%s", appID) }
	EndpointApplicationStatus      = func(appID string) string { return fmt.Sprintf("/apps/%s/status", appID) }
	EndpointApplicationLogs        = func(appID string) string { return fmt.Sprintf("/apps/%s/logs", appID) }
	EndpointApplicationMetrics     = func(appID string) string { return fmt.Sprintf("/apps/%s/metrics", appID) }
	EndpointApplicationRealtime    = func(appID string) string { return fmt.Sprintf("/apps/%s/realtime", appID) }
	EndpointApplicationStart       = func(appID string) string { return fmt.Sprintf("/apps/%s/start", appID) }
	EndpointApplicationRestart     = func(appID string) string { return fmt.Sprintf("/apps/%s/restart", appID) }
	EndpointApplicationStop        = func(appID string) string { return fmt.Sprintf("/apps/%s/stop", appID) }
	EndpointApplicationCommit      = func(appID string) string { return fmt.Sprintf("/apps/%s/commit", appID) }

	// Application Snapshots
	EndpointApplicationSnapshots       = func(appID string) string { return fmt.Sprintf("/apps/%s/snapshots", appID) }
	EndpointApplicationSnapshotRestore = func(appID string) string { return fmt.Sprintf("/apps/%s/snapshots/restore", appID) }

	// Application Environment Variables
	EndpointApplicationEnvs = func(appID string) string { return fmt.Sprintf("/apps/%s/envs", appID) }

	// Application File Manager
	EndpointApplicationFiles    = func(appID string) string { return fmt.Sprintf("/apps/%s/files", appID) }
	EndpointApplicationFileRead = func(appID string) string { return fmt.Sprintf("/apps/%s/files/content", appID) }

	// Application Deployments
	EndpointApplicationDeployments       = func(appID string) string { return fmt.Sprintf("/apps/%s/deployments", appID) }
	EndpointApplicationCurrentDeployment = func(appID string) string { return fmt.Sprintf("/apps/%s/deployments/current", appID) }
	EndpointApplicationDeployWebhook     = func(appID string) string { return fmt.Sprintf("/apps/%s/deploy/webhook", appID) }
	EndpointApplicationGithubApp         = func(appID string) string { return fmt.Sprintf("/apps/%s/deploy/github-app", appID) }

	// Application Network
	EndpointApplicationDNS          = func(appID string) string { return fmt.Sprintf("/apps/%s/network/dns", appID) }
	EndpointApplicationCustomDomain = func(appID string) string { return fmt.Sprintf("/apps/%s/network/custom", appID) }
	EndpointApplicationAnalytics    = func(appID string) string { return fmt.Sprintf("/apps/%s/network/analytics", appID) }
	EndpointApplicationNetErrors    = func(appID string) string { return fmt.Sprintf("/apps/%s/network/errors", appID) }
	EndpointApplicationNetLogs      = func(appID string) string { return fmt.Sprintf("/apps/%s/network/logs", appID) }
	EndpointApplicationNetPerf      = func(appID string) string { return fmt.Sprintf("/apps/%s/network/performance", appID) }
	EndpointApplicationPurgeCache   = func(appID string) string { return fmt.Sprintf("/apps/%s/network/purge_cache", appID) }

	// Databases
	EndpointDatabases               = func() string { return "/databases" }
	EndpointDatabaseListStatus      = func() string { return "/databases/status" }
	EndpointDatabaseInformation     = func(dbID string) string { return fmt.Sprintf("/databases/%s", dbID) }
	EndpointDatabaseStatus          = func(dbID string) string { return fmt.Sprintf("/databases/%s/status", dbID) }
	EndpointDatabaseMetrics         = func(dbID string) string { return fmt.Sprintf("/databases/%s/metrics", dbID) }
	EndpointDatabaseStart           = func(dbID string) string { return fmt.Sprintf("/databases/%s/start", dbID) }
	EndpointDatabaseStop            = func(dbID string) string { return fmt.Sprintf("/databases/%s/stop", dbID) }
	EndpointDatabaseCertificate     = func(dbID string) string { return fmt.Sprintf("/databases/%s/credentials/certificate", dbID) }
	EndpointDatabaseCredentials     = func(dbID string) string { return fmt.Sprintf("/databases/%s/credentials/reset", dbID) }
	EndpointDatabaseSnapshots       = func(dbID string) string { return fmt.Sprintf("/databases/%s/snapshots", dbID) }
	EndpointDatabaseSnapshotRestore = func(dbID string) string { return fmt.Sprintf("/databases/%s/snapshots/restore", dbID) }

	// Workspaces
	EndpointWorkspaces            = func() string { return "/workspaces" }
	EndpointWorkspaceInformation  = func(workspaceID string) string { return fmt.Sprintf("/workspaces/%s", workspaceID) }
	EndpointWorkspaceLeave        = func() string { return "/workspaces/leave" }
	EndpointWorkspaceApplications = func() string { return "/workspaces/applications" }
	EndpointWorkspaceMembers      = func() string { return "/workspaces/members" }
	EndpointWorkspaceInviteCode   = func() string { return "/workspaces/members/code" }
)

Query parameters (scope, path, rawData, start/end, ...) are appended via WithQueryParam so they are always URL-encoded.

Functions

func ErrorCode 

func ErrorCode(err error) string

ErrorCode extracts the Square Cloud error code from err, or "" if err is not an APIError.

func IsRateLimit 

func IsRateLimit(err error) bool

IsRateLimit reports whether err is a rate-limit rejection (including the short KEEP_CALM retry and legacy DELAY_NOW/RATELIMIT codes).

Types

type APIError 

type APIError struct {
	StatusCode int
	Code       string
	Message    string
}

APIError is a non-2xx response from the Square Cloud API. Code carries the machine-readable error code (e.g. "APP_NOT_FOUND", "ACCESS_DENIED", "RATE_LIMIT_EXCEEDED") — the canonical list lives in @squarecloud/api-types' APIErrorCode.

func (*APIError) Error 

func (e *APIError) Error() string

type Applications 

type Applications interface {
	GetApplications(options ...RequestOpt) ([]squarecloud.UserApplication, error)
	GetApplicationListStatus(options ...RequestOpt) ([]squarecloud.ApplicationStatusListItem, error)
	GetApplicationDomains(options ...RequestOpt) ([]squarecloud.AppDomain, error)
	GetLoadBalancers(options ...RequestOpt) (squarecloud.LoadBalancers, error)

	PostApplications(reader io.Reader, options ...RequestOpt) (*squarecloud.ApplicationUploaded, error)

	GetApplication(appID string, options ...RequestOpt) (squarecloud.Application, error)
	GetApplicationStatus(appID string, options ...RequestOpt) (squarecloud.ApplicationStatus, error)
	GetApplicationStatusRaw(appID string, options ...RequestOpt) (squarecloud.ApplicationStatusRaw, error)
	GetApplicationLogs(appID string, options ...RequestOpt) (squarecloud.ApplicationLogs, error)
	GetApplicationMetrics(appID string, options ...RequestOpt) ([]squarecloud.MetricPoint, error)
	PostApplicationSignal(appID string, signal squarecloud.ApplicationSignal, options ...RequestOpt) error
	PostApplicationCommit(appID string, reader io.Reader, options ...RequestOpt) error
	DeleteApplication(appID string, options ...RequestOpt) error

	// ApplicationRealtime opens the SSE stream of /apps/{id}/realtime. The
	// caller must Close the returned stream.
	ApplicationRealtime(appID string, options ...RequestOpt) (*RealtimeStream, error)

	GetApplicationSnapshots(appID string, options ...RequestOpt) ([]squarecloud.Snapshot, error)
	CreateApplicationSnapshot(appID string, options ...RequestOpt) (squarecloud.SnapshotCreated, error)
	RestoreApplicationSnapshot(appID, snapshotID, versionID string, options ...RequestOpt) error

	GetApplicationEnvs(appID string, options ...RequestOpt) (squarecloud.EnvVars, error)
	SetApplicationEnvs(appID string, envs squarecloud.EnvVars, options ...RequestOpt) (squarecloud.EnvVars, error)
	ReplaceApplicationEnvs(appID string, envs squarecloud.EnvVars, options ...RequestOpt) (squarecloud.EnvVars, error)
	DeleteApplicationEnvs(appID string, keys []string, options ...RequestOpt) error

	GetApplicationFiles(appID, path string, options ...RequestOpt) ([]squarecloud.FileInfo, error)
	ReadApplicationFile(appID, path string, options ...RequestOpt) (squarecloud.FileContent, error)
	PutApplicationFile(appID, path string, content []byte, options ...RequestOpt) (squarecloud.FileWritten, error)
	MoveApplicationFile(appID, path, to string, options ...RequestOpt) error
	DeleteApplicationFile(appID, path string, options ...RequestOpt) error

	GetApplicationDeployments(appID string, options ...RequestOpt) ([][]squarecloud.Deployment, error)
	GetApplicationCurrentDeployment(appID string, options ...RequestOpt) (squarecloud.DeploymentCurrent, error)
	PostApplicationDeployWebhook(appID, accessToken string, options ...RequestOpt) (squarecloud.GithubWebhook, error)
	LinkApplicationGithubApp(appID, repositoryName, repositoryBranch string, options ...RequestOpt) (squarecloud.GithubAppLink, error)
	UnlinkApplicationGithubApp(appID string, options ...RequestOpt) error

	GetApplicationDNS(appID string, options ...RequestOpt) ([]squarecloud.DNSRecord, error)
	SetApplicationCustomDomain(appID, domain string, options ...RequestOpt) error
	GetApplicationAnalytics(appID string, start, end time.Time, options ...RequestOpt) (squarecloud.NetworkAnalytics, error)
	GetApplicationNetworkErrors(appID string, start, end time.Time, options ...RequestOpt) (squarecloud.NetworkErrors, error)
	GetApplicationNetworkLogs(appID string, start, end time.Time, options ...RequestOpt) ([]squarecloud.NetworkLog, error)
	GetApplicationNetworkPerformance(appID string, start, end time.Time, options ...RequestOpt) (squarecloud.NetworkPerformance, error)
	PurgeApplicationCache(appID string, options ...RequestOpt) error
}

func NewApplications 

func NewApplications(client Client) Applications

type Client 

type Client interface {
	HTTPClient() *http.Client
	// Request performs a call and unmarshals the JSON response into rsBody.
	Request(method, url string, rqBody []byte, rsBody any, options ...RequestOpt) error
	// Stream performs a call and returns the raw response body without
	// reading it — used for server-sent events. The caller must Close it.
	Stream(method, url string, options ...RequestOpt) (io.ReadCloser, error)

	Close()
}

func NewClient 

func NewClient(token string, opts ...ConfigOpt) Client

type Config 

type Config struct {
	Logger     *slog.Logger
	HTTPClient *http.Client
	URL        string
	UserAgent  string
}

func DefaultConfig 

func DefaultConfig() *Config

func (*Config) Apply 

func (c *Config) Apply(opts []ConfigOpt)

type ConfigOpt 

type ConfigOpt func(config *Config)

func WithHTTPClient 

func WithHTTPClient(httpClient *http.Client) ConfigOpt

func WithLogger 

func WithLogger(logger *slog.Logger) ConfigOpt

func WithURL 

func WithURL(url string) ConfigOpt

func WithUserAgent 

func WithUserAgent(userAgent string) ConfigOpt

type Databases 

type Databases interface {
	GetDatabases(options ...RequestOpt) ([]squarecloud.UserDatabase, error)
	GetDatabaseListStatus(options ...RequestOpt) ([]squarecloud.DatabaseStatusListItem, error)
	CreateDatabase(create squarecloud.DatabaseCreateOptions, options ...RequestOpt) (squarecloud.DatabaseCreated, error)

	GetDatabase(dbID string, options ...RequestOpt) (squarecloud.Database, error)
	UpdateDatabase(dbID string, update squarecloud.DatabaseUpdateOptions, options ...RequestOpt) error
	DeleteDatabase(dbID string, options ...RequestOpt) error
	GetDatabaseStatus(dbID string, options ...RequestOpt) (squarecloud.DatabaseStatus, error)
	GetDatabaseStatusRaw(dbID string, options ...RequestOpt) (squarecloud.DatabaseStatusRaw, error)
	GetDatabaseMetrics(dbID string, options ...RequestOpt) ([]squarecloud.MetricPoint, error)
	StartDatabase(dbID string, options ...RequestOpt) error
	StopDatabase(dbID string, options ...RequestOpt) error

	GetDatabaseCertificate(dbID string, options ...RequestOpt) (squarecloud.DatabaseCertificate, error)
	// ResetDatabaseCredentials rotates a credential. The returned password is
	// non-empty only for reset type "password" and is shown only once.
	ResetDatabaseCredentials(dbID string, reset squarecloud.DatabaseResetType, options ...RequestOpt) (squarecloud.DatabasePasswordReset, error)

	GetDatabaseSnapshots(dbID string, options ...RequestOpt) ([]squarecloud.Snapshot, error)
	CreateDatabaseSnapshot(dbID string, options ...RequestOpt) (squarecloud.SnapshotCreated, error)
	RestoreDatabaseSnapshot(dbID, snapshotID, versionID string, options ...RequestOpt) error
}

func NewDatabases 

func NewDatabases(client Client) Databases

type RealtimeStream 

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

RealtimeStream reads server-sent events from /apps/{id}/realtime. Iterate with Next until io.EOF (or context cancellation) and always Close.

func (*RealtimeStream) Close 

func (r *RealtimeStream) Close() error

func (*RealtimeStream) Next 

func (r *RealtimeStream) Next() (squarecloud.RealtimeEvent, error)

Next blocks until the next complete SSE event arrives. It returns io.EOF when the server closes the stream (the connection has a 10-minute TTL — reconnect by calling ApplicationRealtime again).

type RequestConfig 

type RequestConfig struct {
	Request *http.Request
	Ctx     context.Context
}

func DefaultRequestConfig 

func DefaultRequestConfig(req *http.Request) *RequestConfig

func (*RequestConfig) Apply 

func (c *RequestConfig) Apply(opts []RequestOpt)

type RequestOpt 

type RequestOpt func(config *RequestConfig)

func WithContext 

func WithContext(ctx context.Context) RequestOpt

WithContext attaches ctx to the outgoing request, enabling cancellation and deadlines.

func WithHeader 

func WithHeader(key string, value string) RequestOpt

func WithQueryParam 

func WithQueryParam(param string, value any) RequestOpt

func WithToken 

func WithToken(token string) RequestOpt

type Rest 

type Rest interface {
	SelfUser(opts ...RequestOpt) (squarecloud.User, error)
	UserSnapshots(scope squarecloud.SnapshotScope, opts ...RequestOpt) ([]squarecloud.Snapshot, error)
	ServiceStatus(opts ...RequestOpt) (squarecloud.ServiceStatus, error)

	Applications
	Databases
	Workspaces
}

func New 

func New(client Client) Rest

type Workspaces 

type Workspaces interface {
	GetWorkspaces(options ...RequestOpt) ([]squarecloud.Workspace, error)
	CreateWorkspace(name string, options ...RequestOpt) (squarecloud.WorkspaceCreated, error)
	GetWorkspace(workspaceID string, options ...RequestOpt) (squarecloud.Workspace, error)
	DeleteWorkspace(workspaceID string, options ...RequestOpt) error
	LeaveWorkspace(workspaceID string, options ...RequestOpt) error

	AddWorkspaceApplication(workspaceID, appID string, options ...RequestOpt) error
	RemoveWorkspaceApplication(workspaceID, appID string, options ...RequestOpt) error

	// AddWorkspaceMember adds a member by invite code (see
	// GetWorkspaceInviteCode — the code is generated by the joining user).
	AddWorkspaceMember(workspaceID, code string, group squarecloud.WorkspaceMemberGroup, options ...RequestOpt) error
	UpdateWorkspaceMember(workspaceID, memberID string, group squarecloud.WorkspaceMemberGroup, options ...RequestOpt) error
	RemoveWorkspaceMember(workspaceID, memberID string, options ...RequestOpt) error
	// GetWorkspaceInviteCode generates the caller's single-use invite code,
	// valid for 5 minutes.
	GetWorkspaceInviteCode(options ...RequestOpt) (squarecloud.WorkspaceInviteCode, error)
}

func NewWorkspaces 

func NewWorkspaces(client Client) Workspaces

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.