transport

Documentation

Overview

Package transport is the SDK's HTTP layer. It is internal — callers should use the resource modules on the Client (client.Sessions().List(), etc.) rather than constructing requests directly.

Responsibilities:

• One *http.Client per SDK Client (connection reuse).
• Inject Authorization: Bearer + X-API-Key headers when present.
• Inject vx-request-id and traceparent for end-to-end tracing.
• Convert non-2xx responses into the typed error hierarchy in errors/errors.go.
• Bounded retry on NetworkError / 5xx / 429 (exponential backoff).

Index

• Variables
• func JoinURL(base, path string) string
• type Doer
• type FilePart
• type Transport
  • func (t *Transport) BytesWithHeaders(ctx context.Context, op, method, url string, headers map[string]string) ([]byte, error)
  • func (t *Transport) JSON(ctx context.Context, op, method, url string, body, out any) error
  • func (t *Transport) JSONWithHeaders(ctx context.Context, op, method, url string, body, out any, ...) error
  • func (t *Transport) Multipart(ctx context.Context, op, url string, fields map[string]string, ...) error
  • func (t *Transport) MultipartWithHeaders(ctx context.Context, op, url string, fields map[string]string, ...) error

Variables

var ErrUnsupported = fmt.Errorf("vxsdk: operation not supported by this server")

Sentinel for callers that want to hint a path is unsupported.

Functions

func JoinURL

func JoinURL(base, path string) string

joinURL concatenates a base and path with exactly one slash separator. Exposed because resource modules call it.

Types

type Doer

type Doer interface {
	Do(*http.Request) (*http.Response, error)
}

Doer is the minimal HTTP client interface the transport layer needs. *http.Client satisfies it; tests can substitute a fake.

type FilePart

type FilePart struct {
	// Field is the form field name (e.g. "script_file", "compose_file").
	Field string
	// Filename is the basename surfaced to the server (e.g. "install.sh").
	Filename string
	// Content is the raw bytes of the file.
	Content []byte
	// ContentType is optional; defaults to application/octet-stream.
	ContentType string
}

FilePart describes one in-memory file to attach to a multipart upload. Path-on-disk uploads are intentionally not supported — callers should read the bytes themselves so the SDK never touches the filesystem on behalf of the caller.

type Transport

type Transport struct {
	Doer          Doer
	UserAgent     string
	Authorization func() (bearer, apiKey string) // called per-request; nil means anonymous
	// NodeURL, when set, identifies the tenant-node base URL. For requests
	// whose URL starts with NodeURL and where a Bearer JWT is present, the
	// X-API-Key header is suppressed. The node developer-key middleware
	// accepts a lone Bearer, but a stale or cross-workspace X-API-Key sent
	// alongside the JWT makes it strict-compare and 403 ("not valid for
	// this workspace"). Control-plane (Infinity) requests keep X-API-Key.
	NodeURL string
	// RefreshOn401, if non-nil, is invoked exactly once per request when a
	// 401 response is received. On success the request is replayed with the
	// updated Authorization headers. Use this to wire automatic token
	// refresh from a long-lived API key.
	RefreshOn401 func(ctx context.Context) error
	MaxRetries   int           // default 3 if zero
	BaseDelay    time.Duration // default 200ms if zero
}

Transport wraps a Doer with auth header injection and typed error mapping.

func (*Transport) BytesWithHeaders

func (t *Transport) BytesWithHeaders(ctx context.Context, op, method, url string, headers map[string]string) ([]byte, error)

BytesWithHeaders performs a non-JSON HTTP request and returns the raw response body. Used by binary endpoints like dataset/embedding downloads where the body is a zip/tar/csv rather than JSON. Auth, retry, refresh, User-Agent and request-id behavior mirrors JSONWithHeaders.

func (*Transport) JSON

func (t *Transport) JSON(ctx context.Context, op, method, url string, body, out any) error

JSON performs an HTTP request with a JSON body (if body != nil) and decodes the JSON response into out (if out != nil). The op string is used in error messages and traces.

func (*Transport) JSONWithHeaders

func (t *Transport) JSONWithHeaders(ctx context.Context, op, method, url string, body, out any, headers map[string]string) error

JSONWithHeaders is JSON with extra request headers merged in — e.g. X-Tenant-ID for the agentcontrol surface. The transport's own headers (Authorization, X-API-Key, Content-Type, Accept, User-Agent, vx-request-id) are authoritative and must not be supplied here.

func (*Transport) Multipart

func (t *Transport) Multipart(
	ctx context.Context,
	op, url string,
	fields map[string]string,
	files []FilePart,
	out any,
) error

Multipart performs a multipart/form-data POST to url with the given string fields and file parts, then decodes the JSON response into out.

Used by /api/v2/tenant/install/script, /api/v2/tenant/container/deploy, /api/v2/tenant/provision/docker-compose/custom — every backend handler that accepts SSH-flag form fields plus optional file uploads.

func (*Transport) MultipartWithHeaders

func (t *Transport) MultipartWithHeaders(
	ctx context.Context,
	op, url string,
	fields map[string]string,
	files []FilePart,
	out any,
	headers map[string]string,
) error

MultipartWithHeaders is Multipart with extra request headers merged in (e.g. X-Tenant-ID for agentcontrol dataset uploads). The transport's own headers are authoritative and must not be supplied here.