api

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

type BackendOptions struct {
	// The scheme and hostname for contacting the server, not including a final
	// slash. For example, "http://localhost:8080".
	BaseURL *url.URL

	// Logger for HTTP operations.
	Logger *slog.Logger

	// W&B API key.
	APIKey string
}

type Client interface {
	// Sends an HTTP request to the W&B backend.
	//
	// It is guaranteed that the response is non-nil unless there is an error.
	Send(*Request) (*http.Response, error)

	// Sends an arbitrary HTTP request.
	//
	// This is used for libraries that accept a custom HTTP client that they
	// then use to make requests to the backend, like GraphQL. If the request
	// URL matches the backend's base URL, there's special handling as in
	// Send().
	//
	// It is guaranteed that the response is non-nil unless there is an error.
	Do(*http.Request) (*http.Response, error)
}

type ClientOptions struct {
	// Maximum number of retries to make for retryable requests.
	RetryMax int

	// Minimum time to wait between retries.
	RetryWaitMin time.Duration

	// Maximum time to wait between retries.
	RetryWaitMax time.Duration

	// Function that determines whether to retry based on the response.
	//
	// If nil, then retries are made on connection errors and server errors
	// (HTTP status code >=500).
	RetryPolicy retryablehttp.CheckRetry

	// Timeout for HTTP requests.
	//
	// This is the time to wait for an individual HTTP request to complete
	// before considering it as failed. It does not include retries: each retry
	// starts a new timeout.
	NonRetryTimeout time.Duration

	// Additional headers to pass in each request to the backend.
	//
	// Note that these are only passed when communicating with the W&B backend.
	// In particular, they are not sent if using this client to send
	// arbitrary HTTP requests.
	ExtraHeaders map[string]string

	// Allows the client to peek at the network traffic, can preform any action
	// on the request and response. Need to make sure that the response body is
	// available to read by later stages.
	NetworkPeeker Peeker
}

type Peeker interface {
	Peek(*http.Request, *http.Response)
}

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

type RateLimitHeaders struct {
	// The RateLimit-Remaining header.
	//
	// Guaranteed non-negative.
	Remaining float64

	// The RateLimit-Reset header.
	//
	// Guaranteed non-negative.
	Reset float64
}

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

type RateLimitTrackerParams struct {
	// Minimum rate limit in requests per second.
	MinPerSecond float64

	// Maximum rate limit in requests per second.
	MaxPerSecond float64

	// Smoothing factor in range [0, 1).
	//
	// The closer this is to 0, the faster the rate is updated based on
	// response headers.
	Smoothing float64

	// Minimum number of requests in an estimation window.
	//
	// Setting above 1 causes optimal rate limit estimates to be averaged out
	// over more requests.
	MinRequestsForEstimate uint64
}

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

type Request struct {
	// The standard HTTP method.
	Method string

	// The request path, not including the scheme or hostname.
	//
	// Example: "/files/a/b/c/file_stream".
	Path string

	// The request body or nil.
	//
	// Since requests may be retried, this is always a byte slice rather than
	// an [io.ReadCloser] as in Go's standard HTTP package.
	Body []byte

	// Additional HTTP headers to include in request.
	//
	// These are sent in addition to any headers set automatically by the
	// client, such as for auth. The client headers take precedence.
	Headers map[string]string
}

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