request

package
v4.0.0-rc1 Latest Latest
Warning

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

 Go to latest Published: Aug 29, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package request contains the lower-level HTTP, SSE, and JSON utilities used by the SDK to build, send, and process Hugging Face API requests.

Index

Constants

View Source 
const (
	// DefaultBaseURL is the default HuggingFace API endpoint.
	DefaultBaseURL = "https://router.huggingface.co"
	// DefaultToken is the default authentication token (empty string).
	DefaultToken = ""
	// DefaultModel is the default model to use.
	DefaultModel = ""
	// DefaultProvider is the default inference provider.
	DefaultProvider = ""
	// DefaultMaxResponseBodyBytes caps the amount of response data read into memory by default.
	DefaultMaxResponseBodyBytes int64 = 1 << 20 // 1 MiB
)

Variables

This section is empty.

Functions

func DefaultHTTPClient 

func DefaultHTTPClient() *http.Client

DefaultHTTPClient returns a new HTTP client configured with a cloned default transport.

func Do 

func Do(
	opts Options,
	method string,
	path string,
	body io.Reader,
) (*http.Response, error)

Do performs an HTTP request with the provided options and returns the response. It creates a new HTTP request with the given method, path, and body, adds authorization and custom headers, and executes the request using the configured HTTP client. For HTTP status codes >= 400, it returns an *hferrors.APIError. The caller must close resp.Body on success.

func DoBytes 

func DoBytes(
	opts Options,
	method string,
	path string,
	data []byte,
) (*http.Response, error)

DoBytes performs an HTTP request with a byte slice body. It is a convenience wrapper around Do that converts the byte slice to an io.Reader. The caller must close resp.Body on success.

func DoBytesRaw 

func DoBytesRaw(
	opts Options,
	method string,
	path string,
	data []byte,
) (*http.Response, error)

DoBytesRaw performs an HTTP request with a byte slice body and returns the response without translating non-2xx status codes into SDK errors. It is a convenience wrapper around DoRaw that converts the byte slice to an io.Reader. The caller must close resp.Body on success.

func DoJSON 

func DoJSON[TReq any, TResp any](
	opts Options,
	method string,
	path string,
	reqBody TReq,
) (resp TResp, err error)

DoJSON performs an HTTP request with a JSON request body and expects a JSON response. It marshals the request body to JSON, sends the request, and unmarshals the response into the specified response type. The function uses Go generics to provide type-safe request and response handling.

Type parameters:

  • TReq: The type of the request body
  • TResp: The type of the response body

Returns an error if JSON marshaling/unmarshaling fails or the HTTP request fails. For HTTP errors, Do returns an *errors.APIError which includes the status code, response body, and other metadata.

func DoRaw 

func DoRaw(
	opts Options,
	method string,
	path string,
	body io.Reader,
) (*http.Response, error)

DoRaw performs an HTTP request with the provided options and returns the response without translating non-2xx status codes into SDK errors. The caller must close resp.Body on success.

func NormalizeContext 

func NormalizeContext(ctx context.Context) context.Context

NormalizeContext returns ctx when non-nil, otherwise context.Background.

Types

type JSONStream 

type JSONStream[T any] struct {
	// contains filtered or unexported fields
}

JSONStream consumes JSON SSE events produced by DoJSONStream.

func DoJSONStream 

func DoJSONStream[TReq any, TResp any](
	opts Options,
	method string,
	path string,
	reqBody TReq,
) (*JSONStream[TResp], error)

DoJSONStream performs an HTTP request with a JSON body and returns a streaming JSON response. The response body must be a Server-Sent Events (SSE) stream where each data chunk contains JSON. Callers are responsible for closing the returned stream to release resources.

func (*JSONStream[T]) Close 

func (s *JSONStream[T]) Close() error

Close releases the underlying stream resources.

func (*JSONStream[T]) Recv 

func (s *JSONStream[T]) Recv(ctx context.Context) (out T, err error)

Recv blocks until the next JSON event is available or the stream ends. It skips keepalive events, treats data: [DONE] as EOF, and unmarshals each chunk into T.

type Option 

type Option func(*Options)

Option is a function type that modifies Options. It follows the functional options pattern for flexible configuration. Custom options that set Headers should avoid reusing mutable header maps if they want to preserve the defensive-copy behavior of built-in helpers.

func WithBaseURL 

func WithBaseURL(u string) Option

WithBaseURL returns an Option that sets the base URL for API requests. The base URL must not include query parameters or fragments.

func WithContext 

func WithContext(ctx context.Context) Option

WithContext returns an Option that sets the context for API requests.

func WithDefaultHTTPClient 

func WithDefaultHTTPClient() Option

WithDefaultHTTPClient returns an Option that sets the default HTTP client.

func WithDefaultHeader 

func WithDefaultHeader(key, value string) Option

WithDefaultHeader returns an Option that sets a header only if missing or empty.

func WithHTTPClientFactory 

func WithHTTPClientFactory(factory func() http.Client) Option

WithHTTPClientFactory returns an Option that sets a client created by the factory. The factory should return a fresh client value; avoid sharing mutable internals like Transport unless synchronized. If the factory is nil, the HTTP client is set to nil.

func WithHeader 

func WithHeader(key, value string) Option

WithHeader returns an Option that sets a single header applied to every request.

func WithHeaders 

func WithHeaders(h http.Header) Option

WithHeaders returns an Option that sets custom headers applied to every request, overriding any existing values for matching keys. The provided map is copied to avoid unexpected mutations by callers.

func WithMaxResponseBodyBytes 

func WithMaxResponseBodyBytes(n int64) Option

WithMaxResponseBodyBytes returns an Option that sets the maximum response size to read.

func WithModel 

func WithModel(m string) Option

WithModel returns an Option that sets the model to use for API requests.

func WithProvider 

func WithProvider(p string) Option

WithProvider returns an Option that sets the provider for API requests.

func WithToken 

func WithToken(t string) Option

WithToken returns an Option that sets the authentication token for API requests.

func WithUserAgent 

func WithUserAgent(ua string) Option

WithUserAgent returns an Option that sets the User-Agent header value.

func WithUserAgentSuffix 

func WithUserAgentSuffix(suffix string) Option

WithUserAgentSuffix returns an Option that appends a suffix to the SDK user agent string.

type Options 

type Options struct {
	BaseURL              string
	Token                string
	Model                string
	Provider             string
	UserAgent            string
	Headers              http.Header
	MaxResponseBodyBytes int64
	HTTPClient           *http.Client
	// contains filtered or unexported fields
}

Options holds configuration settings for API requests. Built-in option helpers return a new value and defensively clone headers, while context and the HTTP client are shared as-is. Custom options should avoid reusing mutable header maps if they want the same defensive-copy behavior.

func NewOptions 

func NewOptions() Options

NewOptions creates a new Options instance with default values. The returned options use a background context, default endpoints, and the default HTTP client.

func (Options) Context 

func (o Options) Context() context.Context

Context returns the configured context or context.Background if none was provided.

func (Options) Validate 

func (o Options) Validate() error

Validate returns a configuration error if the options are invalid.

func (Options) With 

func (o Options) With(opts ...Option) Options

With returns a new Options instance with the provided options applied. This method creates a copy of the current options and applies modifications to it.

func (Options) WithBaseURL 

func (o Options) WithBaseURL(u string) Options

WithBaseURL returns a new Options instance with the base URL updated. The base URL must not include query parameters or fragments.

func (Options) WithContext 

func (o Options) WithContext(ctx context.Context) Options

WithContext returns a new Options instance with the context updated.

func (Options) WithDefaultHTTPClient 

func (o Options) WithDefaultHTTPClient() Options

WithDefaultHTTPClient returns a new Options instance that uses the default HTTP client.

func (Options) WithDefaultHeader 

func (o Options) WithDefaultHeader(key, value string) Options

WithDefaultHeader returns a new Options instance with a header set only if the header is missing or empty.

func (Options) WithHTTPClientFactory 

func (o Options) WithHTTPClientFactory(factory func() http.Client) Options

WithHTTPClientFactory returns a new Options instance with an http.Client created by the factory. The factory should return a fresh client value; avoid sharing mutable internals like Transport unless synchronized. If the factory is nil, the HTTP client is set to nil.

func (Options) WithHeader 

func (o Options) WithHeader(key, value string) Options

WithHeader returns a new Options instance with a single header applied.

func (Options) WithHeaders 

func (o Options) WithHeaders(h http.Header) Options

WithHeaders returns a new Options instance with the provided headers applied, overriding any existing values for matching keys.

func (Options) WithMaxResponseBodyBytes 

func (o Options) WithMaxResponseBodyBytes(n int64) Options

WithMaxResponseBodyBytes returns a new Options instance with the response size cap updated.

func (Options) WithModel 

func (o Options) WithModel(m string) Options

WithModel returns a new Options instance with the model updated.

func (Options) WithProvider 

func (o Options) WithProvider(p string) Options

WithProvider returns a new Options instance with the provider updated.

func (Options) WithToken 

func (o Options) WithToken(t string) Options

WithToken returns a new Options instance with the authentication token updated.

func (Options) WithUserAgent 

func (o Options) WithUserAgent(ua string) Options

WithUserAgent returns a new Options instance with the User-Agent value updated.

func (Options) WithUserAgentSuffix 

func (o Options) WithUserAgentSuffix(suffix string) Options

WithUserAgentSuffix returns a new Options instance with a suffix appended to the SDK User-Agent.

type RawEvent 

type RawEvent struct {
	// Data holds the concatenated data lines for the event.
	Data []byte
	// Event indicates the optional "event:" field name.
	Event string
	// ID is the optional "id:" field value.
	ID string
	// Retry holds the parsed reconnection duration when present.
	Retry *time.Duration
}

RawEvent represents a single parsed SSE event payload.

type RawStream 

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

RawStream consumes an SSE response body and exposes parsed events.

func StreamRaw 

func StreamRaw(ctx context.Context, body io.ReadCloser) (*RawStream, error)

StreamRaw starts decoding Server-Sent Events from the provided body. Callers should close the returned RawStream when they are done consuming it so the background goroutine and HTTP body are released promptly (otherwise it will only stop once the server closes the stream).

func (*RawStream) Close 

func (s *RawStream) Close() error

Close stops the decoder and releases the underlying body. It is safe to call multiple times.

func (*RawStream) Recv 

func (s *RawStream) Recv(ctx context.Context) (event RawEvent, err error)

Recv blocks until the next event is available, the provided context is canceled, or the stream ends. It returns io.EOF when no more events remain.

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.