transport

Documentation

Overview

Package transport is the shared HTTP layer used by every public sub-client (chat, responses, images, ...). It owns base-URL handling, authentication, retry, response-size limits, and the SSE stream reader. The package is internal so callers configure it indirectly via the grok.With* options on the root client.

Index

• type APIError
• type SSEStream
  • func (s *SSEStream) Close() error
  • func (s *SSEStream) Next() ([]byte, error)
• type Transport
  • func New(apiKey, baseURL string, client *http.Client) *Transport
  • func NewInsecure(apiKey, baseURL string, client *http.Client) *Transport
  • func (t *Transport) Do(ctx context.Context, method, path string, body, out any) error
  • func (t *Transport) DoMultipart(ctx context.Context, path string, fields map[string]string, ...) error
  • func (t *Transport) DoRaw(ctx context.Context, method, path string, body any) ([]byte, error)
  • func (t *Transport) DoStream(ctx context.Context, method, path string, body any) (io.ReadCloser, error)
  • func (t *Transport) Stream(ctx context.Context, method, path string, body any) (*SSEStream, error)
  • func (t *Transport) WithConcurrency(n int) *Transport
  • func (t *Transport) WithConvID(id string) *Transport

Types

type APIError

type APIError = apierr.APIError

APIError is re-exported so sub-packages can use it without importing apierr directly.

type SSEStream

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

SSEStream reads server-sent events from an HTTP response.

func (*SSEStream) Close

func (s *SSEStream) Close() error

Close releases the underlying HTTP response body.

func (*SSEStream) Next

func (s *SSEStream) Next() ([]byte, error)

type Transport

type Transport struct {
	Client     *http.Client
	BaseURL    string
	APIKey     string
	ConvID     string       // x-grok-conv-id for prompt caching
	MaxRetries int          // 0 = no retry (default)
	Logger     *slog.Logger // nil = no logging

	// MaxResponseBytes caps the body size for non-streaming responses.
	// Zero uses the default (64 MiB). Negative disables. Streaming
	// helpers (Stream, DoStream) bypass this cap by design.
	MaxResponseBytes int64

	// AllowInsecureBaseURL permits http:// base URLs. By default
	// transport.New rejects non-HTTPS base URLs to prevent silent
	// downgrade of the API-key bearer token. Test/dev callers should
	// set this explicitly.
	AllowInsecureBaseURL bool
	// contains filtered or unexported fields
}

Transport handles all HTTP communication with the xAI API.

func New

func New(apiKey, baseURL string, client *http.Client) *Transport

New creates a Transport. If baseURL is empty, the default xAI base URL is used. If client is nil a default http.Client is built with a 5-minute timeout. The base URL must be https:// unless allowInsecureBase is true (use NewInsecure for that).

func NewInsecure

func NewInsecure(apiKey, baseURL string, client *http.Client) *Transport

NewInsecure is like New but accepts http:// base URLs. Use only for tests or for trusted on-network mirrors that do not speak TLS.

func (*Transport) Do

func (t *Transport) Do(ctx context.Context, method, path string, body, out any) error

Do performs a JSON request and decodes the response into out.

func (*Transport) DoMultipart

func (t *Transport) DoMultipart(ctx context.Context, path string, fields map[string]string, fileField, filename string, file io.Reader, out any) error

DoMultipart sends a multipart/form-data POST and decodes the JSON response into out. fields are optional string key-value pairs. Pass a non-nil file with fileField/filename to include a file part; pass nil file for field-only forms (e.g. STT with a URL).

func (*Transport) DoRaw

func (t *Transport) DoRaw(ctx context.Context, method, path string, body any) ([]byte, error)

DoRaw performs a request and returns raw bytes (e.g. for audio).

func (*Transport) DoStream

func (t *Transport) DoStream(ctx context.Context, method, path string, body any) (io.ReadCloser, error)

DoStream performs a request and returns the response body as a ReadCloser. The caller must close the returned body. The MaxResponseBytes cap does not apply to DoStream; the caller controls how much to read.

func (*Transport) Stream

func (t *Transport) Stream(ctx context.Context, method, path string, body any) (*SSEStream, error)

Stream performs a request expecting an SSE (text/event-stream) response.

func (*Transport) WithConcurrency

func (t *Transport) WithConcurrency(n int) *Transport

WithConcurrency returns a shallow copy of t with a semaphore limiting the number of in-flight HTTP calls to n. The semaphore is shared across copies of t that are derived via WithConvID, so the limit applies globally.

func (*Transport) WithConvID

func (t *Transport) WithConvID(id string) *Transport

WithConvID returns a shallow copy of t with ConvID set.