Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNoAPIKey = errors.New("no API key configured")
ErrNoAPIKey is returned when no API key is present in the local configuration.
Functions ¶
func IsAuthError ¶
IsAuthError reports whether err is an authentication or authorisation error.
func IsRetryable ¶
IsRetryable reports whether the given error code represents a transient failure that may succeed if the request is retried.
Types ¶
type APIResponse ¶
type APIResponse struct {
Data []json.RawMessage `json:"data"`
Errors []RunwareError `json:"errors,omitempty"`
}
APIResponse is the top-level envelope returned by the Runware API.
type ErrorCode ¶
type ErrorCode string
ErrorCode is a stable category for a RunwareError. Use it for switch/if statements.
const ( CodeValidation ErrorCode = "validation" CodeAuth ErrorCode = "auth" CodeQuota ErrorCode = "quota" CodeRateLimit ErrorCode = "rateLimit" CodeSafety ErrorCode = "safety" CodeProvider ErrorCode = "provider" CodeTimeout ErrorCode = "timeout" CodeNotFound ErrorCode = "notFound" CodeServerError ErrorCode = "serverError" CodeConnection ErrorCode = "connection" CodeAborted ErrorCode = "aborted" CodeUnknown ErrorCode = "unknown" )
func DeriveCode ¶
DeriveCode maps a raw server-side error code string to a stable ErrorCode. The mapping mirrors the TypeScript SDK's deriveCode function.
type HTTPTransport ¶
type HTTPTransport struct {
// contains filtered or unexported fields
}
HTTPTransport implements Transport using the Runware REST API.
func DialHTTP ¶
func DialHTTP(_ context.Context, apiKey, baseURL string, logger *slog.Logger, opts ...HTTPTransportOption) (*HTTPTransport, error)
DialHTTP creates an HTTP transport for the given API key and base URL. The ctx argument is accepted for interface symmetry but is not used — HTTP is stateless and requires no connection handshake. Default timeout is 120s. Use WithTimeout or WithHTTPClient to override.
func (*HTTPTransport) Close ¶
func (t *HTTPTransport) Close() error
Close is a no-op for HTTP; the transport is stateless.
func (*HTTPTransport) Send ¶
func (t *HTTPTransport) Send(ctx context.Context, tasks []any) ([]json.RawMessage, error)
Send marshals tasks, POSTs to the API, and returns the response data items. API-level errors are converted to Go errors before returning.
type HTTPTransportOption ¶
type HTTPTransportOption func(*httpTransportOptions)
HTTPTransportOption is a functional option for DialHTTP.
func WithHTTPClient ¶
func WithHTTPClient(c *http.Client) HTTPTransportOption
WithHTTPClient replaces the default HTTP client entirely. When provided, WithTimeout has no effect — the caller is responsible for the client's timeout.
func WithTimeout ¶
func WithTimeout(d time.Duration) HTTPTransportOption
WithTimeout sets the HTTP client timeout. Ignored if WithHTTPClient is also provided.
type RunwareError ¶
type RunwareError struct {
// Code is a stable category for this error. Use it for switch/if statements.
Code ErrorCode
// RawCode is the original error code string from the API.
RawCode string
// Message is the human-readable error description.
Message string
// Retryable is true if retrying the same request might succeed.
Retryable bool
// Parameter is the request field that caused the error, if applicable.
Parameter string
// TaskType is the task type of the request that failed.
TaskType string
// TaskUUID is the unique identifier of the failed request.
TaskUUID string
// Documentation is a link to relevant documentation, if available.
Documentation string
// StatusCode is the HTTP status code when the error originated from an HTTP response.
StatusCode int
}
RunwareError is a structured error returned by the Runware API or transport layer.
func CreateRunwareError ¶
func CreateRunwareError(rawCode, message string, details RunwareErrorDetails) *RunwareError
CreateRunwareError constructs a RunwareError from a raw code, message, and optional details.
func ParseAPIError ¶
func ParseAPIError(raw json.RawMessage, statusCode int) *RunwareError
ParseAPIError parses a raw API response body into a RunwareError. It handles three JSON shapes:
[{...}] — array of error items; first element is used
{"errors":[{...}]} — standard API envelope; errors[0] is used
{"error":{...},"taskUUID":"..."} — pre-stream HTTP error; inner object is used
func (*RunwareError) Error ¶
func (e *RunwareError) Error() string
func (*RunwareError) UnmarshalJSON ¶
func (e *RunwareError) UnmarshalJSON(data []byte) error
UnmarshalJSON implements json.Unmarshaler so RunwareError can be decoded directly from an API errors array element.
type RunwareErrorDetails ¶
RunwareErrorDetails carries optional context for CreateRunwareError.
type Transport ¶
type Transport interface {
// Close tears down the connection and releases any associated resources.
Close() error
// Send transmits tasks to the API and returns the raw response data items,
// with any API-level errors already converted to Go errors.
Send(ctx context.Context, tasks []any) ([]json.RawMessage, error)
}
Transport handles the wire protocol for communicating with the Runware API. Implementations are responsible for connection lifecycle and request delivery.
type WSOption ¶
type WSOption func(*WSTransport)
WSOption is a functional option for configuring a WSTransport.
func WithMaxReconnectAttempts ¶
WithMaxReconnectAttempts sets the maximum number of reconnection attempts before the transport gives up and fails all in-flight requests. Default is 10.
func WithPingInterval ¶
WithPingInterval overrides the keepAlive ping interval. Intended for testing; production code should rely on the default (30s).
func WithReconnectBaseDelay ¶
WithReconnectBaseDelay overrides the base delay between reconnect attempts. Intended for testing; production code should rely on the default (1s).
type WSTransport ¶
type WSTransport struct {
// contains filtered or unexported fields
}
WSTransport implements Transport over a persistent WebSocket connection.
The first call to Send establishes the connection and authenticates with the API. Subsequent calls reuse the same connection.
On connection loss the transport reconnects automatically with exponential backoff. In-flight Send calls are preserved across reconnections; the server replays buffered results via the connectionSessionUUID mechanism. Only when the maximum reconnect attempts are exhausted are in-flight calls failed.
Close is terminal — the transport cannot be reused after Close.
func DialWS ¶
func DialWS(ctx context.Context, apiKey, baseURL string, logger *slog.Logger, opts ...WSOption) (*WSTransport, error)
NewWSTransport creates a WebSocket transport for the given API key and base URL. Connect is deferred until the first Send (or an explicit Connect call). DialWS dials a WebSocket connection to the Runware API, performs the authentication handshake, and returns a ready-to-use transport. opts may be used to override reconnect behaviour, ping interval, etc.
func (*WSTransport) Close ¶
func (t *WSTransport) Close() error
Close permanently shuts down the WebSocket connection and unblocks all in-flight Send calls. Close is terminal — the transport cannot be reused afterwards. Safe to call if DialWS succeeded but no Send has been issued yet.
func (*WSTransport) Send ¶
func (t *WSTransport) Send(ctx context.Context, tasks []any) ([]json.RawMessage, error)
Send marshals tasks, writes them to the WebSocket connection, and waits for all expected results for each task UUID.
If a task carries a "numberResults" field (int > 1), Send collects that many result items before returning. All results for all tasks are returned as a flat slice in task order. Defaults to 1 result per task if the field is absent.
Source Files