Documentation
¶
Overview ¶
Package client provides an HTTP client for communicating with the Arcane API.
The client handles authentication, request construction, and response parsing for all API calls. It supports JSON request/response bodies as well as raw multipart uploads.
Creating a Client ¶
The recommended way to create a client is from the CLI configuration:
c, err := client.NewFromConfig()
if err != nil {
return err
}
Making Requests ¶
The client provides convenience methods for common HTTP methods:
resp, err := c.Get(ctx, "/api/images") resp, err := c.Post(ctx, "/api/images/pull", body) resp, err := c.Delete(ctx, "/api/images/abc123")
Index ¶
- type APIResponse
- type Client
- func (c *Client) Delete(ctx context.Context, path string) (*http.Response, error)
- func (c *Client) DeleteJSON[T any](ctx context.Context, path string) (*APIResponse[T], error)
- func (c *Client) DeleteWithBody(ctx context.Context, path string, body any) (*http.Response, error)
- func (c *Client) DoJSON[T any](ctx context.Context, method, path string, body any) (T, error)
- func (c *Client) DoRaw(ctx context.Context, method, path string, body any) ([]byte, error)
- func (c *Client) EnvID() string
- func (c *Client) Get(ctx context.Context, path string) (*http.Response, error)
- func (c *Client) GetJSON[T any](ctx context.Context, path string) (*APIResponse[T], error)
- func (c *Client) Post(ctx context.Context, path string, body any) (*http.Response, error)
- func (c *Client) PostJSON[T any](ctx context.Context, path string, body any) (*APIResponse[T], error)
- func (c *Client) Put(ctx context.Context, path string, body any) (*http.Response, error)
- func (c *Client) PutJSON[T any](ctx context.Context, path string, body any) (*APIResponse[T], error)
- func (c *Client) Request(ctx context.Context, method, path string, body any) (*http.Response, error)
- func (c *Client) RequestRaw(ctx context.Context, method, path string, body io.Reader, ...) (*http.Response, error)
- func (c *Client) SetEnvironment(envID string)
- func (c *Client) SetRetryPolicy(maxAttempts int, baseBackoff, maxBackoff time.Duration)
- func (c *Client) SetTimeout(timeout time.Duration)
- func (c *Client) TestConnection(ctx context.Context) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type APIResponse ¶
type APIResponse[T any] struct { Success bool `json:"success"` Data T `json:"data"` Error string `json:"error,omitempty"` }
APIResponse wraps the standard Arcane API response format. All API responses include a Success field indicating whether the request succeeded, a Data field containing the response payload, and an optional Error field with error details on failure.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is an HTTP client for the Arcane API. It handles authentication via API tokens and provides methods for making HTTP requests to various API endpoints. The client automatically includes authentication headers and handles JSON serialization.
func New ¶
New creates a new API client from the provided configuration. It validates the configuration and returns an error if required fields (ServerURL, APIKey) are missing. The client is initialized with a default 30-second timeout and the configured environment ID.
func NewFromConfig ¶
NewFromConfig loads the CLI configuration from disk and creates a new client. This is the recommended way to create a client in CLI commands. It returns an error if the configuration cannot be loaded or is invalid.
func NewFromConfigUnauthenticated ¶
NewFromConfigUnauthenticated loads config and returns an unauthenticated client.
func NewUnauthenticated ¶
NewUnauthenticated creates a client that can call unauthenticated endpoints (e.g. /api/auth/login). It only validates that server_url is configured.
func (*Client) Delete ¶
Delete makes a DELETE request to the specified path. It is a convenience wrapper around Request for removing resources.
func (*Client) DeleteJSON ¶ added in v2.10.0
DeleteJSON performs a DELETE and decodes the standard API envelope, enforcing HTTP and API success.
func (*Client) DeleteWithBody ¶ added in v2.6.0
DeleteWithBody makes a DELETE request to the specified path with a JSON body. A handful of Arcane delete endpoints — project destroy, for one — take options in the request body rather than as query parameters.
func (*Client) DoJSON ¶
DoJSON performs a request and decodes the response JSON, enforcing a successful HTTP status. Unlike GetJSON/PostJSON it does not require the standard API envelope or its Success flag.
func (*Client) DoRaw ¶
DoRaw performs a request and returns the response payload when status is 2xx.
func (*Client) EnvID ¶
EnvID returns the current environment ID configured for this client. The environment ID is used to scope API requests to a specific environment.
func (*Client) Get ¶
Get makes a GET request to the specified path. It is a convenience wrapper around Request for retrieving resources.
func (*Client) GetJSON ¶ added in v2.10.0
GetJSON performs a GET and decodes the standard API envelope, enforcing HTTP and API success.
func (*Client) Post ¶
Post makes a POST request to the specified path with a JSON body. It is a convenience wrapper around Request for creating resources.
func (*Client) PostJSON ¶ added in v2.10.0
func (c *Client) PostJSON[T any](ctx context.Context, path string, body any) (*APIResponse[T], error)
PostJSON performs a POST with a JSON body and decodes the standard API envelope, enforcing HTTP and API success.
func (*Client) Put ¶
Put makes a PUT request to the specified path with a JSON body. It is a convenience wrapper around Request for updating resources.
func (*Client) PutJSON ¶ added in v2.10.0
func (c *Client) PutJSON[T any](ctx context.Context, path string, body any) (*APIResponse[T], error)
PutJSON performs a PUT with a JSON body and decodes the standard API envelope, enforcing HTTP and API success.
func (*Client) Request ¶
func (c *Client) Request(ctx context.Context, method, path string, body any) (*http.Response, error)
Request makes an HTTP request to the API with JSON body serialization. It constructs the full URL from the base URL and path, serializes the body as JSON (if provided), and includes authentication headers. The caller is responsible for closing the response body.
func (*Client) RequestRaw ¶
func (c *Client) RequestRaw(ctx context.Context, method, path string, body io.Reader, headers map[string]string) (*http.Response, error)
RequestRaw makes an HTTP request with a raw body and custom headers. Unlike Request, this method does not serialize the body as JSON, making it suitable for multipart form uploads and other non-JSON content types. Custom headers can be provided to set Content-Type and other headers.
func (*Client) SetEnvironment ¶
SetEnvironment changes the environment ID for subsequent requests. This allows switching between different Arcane environments without creating a new client instance.
func (*Client) SetRetryPolicy ¶
SetRetryPolicy configures retry behavior for idempotent requests.
func (*Client) SetTimeout ¶
SetTimeout changes the timeout for subsequent requests.
func (*Client) TestConnection ¶
TestConnection tests the API connection by making a request to the version endpoint. It returns nil if the connection is successful, or an error describing the failure. This is useful for verifying configuration before making other API calls.
Source Files