@lovrozagar/honey 0.6.8 → 0.7.1

package/dist/client-go/runtime.go

@@ -0,0 +1,975 @@
+// Code generated by honey. DO NOT EDIT.
+
+package sdk
+
+import (
+	"bytes"
+	"context"
+	"crypto/rand"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"math"
+	"mime/multipart"
+	"net/http"
+	"net/textproto"
+	"net/url"
+	"reflect"
+	"sort"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+)
+
+// RequestContext carries mutable request metadata through OnRequest hook
+// invocations. Hooks may mutate Method, URL, Headers, or Body; mutations are
+// applied to the outgoing request after the full hook chain completes.
+// Selector / IsStale / InvalidatedBy mirror the TS hook ctx and are populated
+// only when the SDK has an active StaleTracker.
+type RequestContext struct {
+	Method        string
+	URL           string
+	Path          string
+	Headers       http.Header
+	Body          []byte
+	IsRetry       bool
+	Selector      string
+	IsStale       bool
+	InvalidatedBy []string
+}
+
+// ResponseContext carries response metadata through OnResponse hook invocations.
+// Hooks may inspect or mutate Body bytes prior to JSON unmarshal in the caller.
+// Status is observational and is not mutated by hooks.
+// Selector / IsStale / InvalidatedBy mirror the TS hook ctx and are populated
+// only when the SDK has an active StaleTracker.
+type ResponseContext struct {
+	Status        int
+	Headers       http.Header
+	Body          []byte
+	IsRetry       bool
+	Selector      string
+	IsStale       bool
+	InvalidatedBy []string
+}
+
+// Config holds all configuration for the SDK client.
+//
+// Timeout bounds a whole regular request, including reading the response body.
+// Streams (SSE, WebSocket, realtime) are not bounded by it. Zero means 30s; a
+// negative value disables the timeout.
+//
+// HTTPClient defaults to a client that does not follow redirects to another
+// host (the 3xx response is returned as an error instead), so custom auth
+// headers never reach a different origin.
+//
+// MaxResponseBytes caps a buffered response body. Zero means 100 MiB; a
+// negative value disables the cap.
+type Config struct {
+	BaseURL          string
+	BearerToken      string
+	Headers          map[string]string
+	Timeout          time.Duration
+	ThrowOnError     bool
+	StaleMaxEntries  int
+	Invalidation     *InvalidationConfig
+	OnAuthExpired    func(context.Context) (string, error)
+	HTTPClient       *http.Client
+	AuthHeaderName   string
+	AuthHeaderPrefix string
+	OnRequest        []func(*RequestContext) error
+	OnResponse       []func(*ResponseContext) error
+	OnLog            func(LogEntry)
+	MaxResponseBytes int64
+
+	auth *authState
+}
+
+const (
+	defaultTimeout          = 30 * time.Second
+	defaultMaxResponseBytes = 100 << 20
+	maxErrorMessageRunes    = 512
+)
+
+// authState holds the current bearer token so a refreshed token is reused by
+// later calls, and serializes refreshes so N concurrent 401s refresh once.
+type authState struct {
+	mu    sync.Mutex
+	token string
+}
+
+func (a *authState) current(cfg Config) string {
+	if a == nil {
+		return cfg.BearerToken
+	}
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	return a.token
+}
+
+// refresh calls OnAuthExpired unless another call already replaced rejected.
+func (a *authState) refresh(ctx context.Context, cfg Config, rejected string) (string, error) {
+	if a == nil {
+		return cfg.OnAuthExpired(ctx)
+	}
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	if a.token != rejected {
+		return a.token, nil
+	}
+	token, err := cfg.OnAuthExpired(ctx)
+	if err != nil {
+		return "", err
+	}
+	a.token = token
+	return token, nil
+}
+
+// prepareConfig fills defaults. NewClient calls it once.
+func prepareConfig(cfg Config) Config {
+	if cfg.HTTPClient == nil {
+		cfg.HTTPClient = &http.Client{CheckRedirect: sameHostRedirects}
+	}
+	if cfg.Timeout == 0 {
+		cfg.Timeout = defaultTimeout
+	}
+	if cfg.MaxResponseBytes == 0 {
+		cfg.MaxResponseBytes = defaultMaxResponseBytes
+	}
+	cfg.auth = &authState{token: cfg.BearerToken}
+	return cfg
+}
+
+// sameHostRedirects follows redirects on the same scheme and host only.
+func sameHostRedirects(req *http.Request, via []*http.Request) error {
+	if len(via) >= 10 {
+		return errors.New("honey: stopped after 10 redirects")
+	}
+	first := via[0].URL
+	if req.URL.Scheme != first.Scheme || req.URL.Host != first.Host {
+		return http.ErrUseLastResponse
+	}
+	return nil
+}
+
+// LogEntry is the payload passed to Config.OnLog. Consumers plug in their own
+// logger; the SDK never formats, levels, or persists. Status is a pointer so
+// nil encodes "omitted" (request_start) without colliding with a real 0 status.
+// Err is the underlying error on the "error" event; nil otherwise. JSON tags
+// match the TS/Python LogEntry shape for cross-language consumer parity.
+type LogEntry struct {
+	Level      string `json:"level"`
+	Event      string `json:"event"`
+	Operation  string `json:"operation"`
+	DurationMs int64  `json:"duration_ms"`
+	Status     *int   `json:"status,omitempty"`
+	Err        error  `json:"-"`
+}
+
+// emitLog invokes the OnLog callback if configured, swallowing any panic so a
+// faulty logger cannot break the request path. Mirrors Python _emit_log /
+// TS optional-chained call.
+func emitLog(cfg Config, entry LogEntry) {
+	if cfg.OnLog == nil {
+		return
+	}
+	defer func() {
+		_ = recover()
+	}()
+	cfg.OnLog(entry)
+}
+
+func errStatus(err error) *int {
+	var apiErr APIError
+	if errors.As(err, &apiErr) {
+		s := apiErr.Status()
+		return &s
+	}
+	return nil
+}
+
+// InvalidationConfig controls cache invalidation behaviour. StaleTime is in
+// milliseconds; ≤0 disables the tracker. StaleMaxEntries caps the LRU map.
+// MaxSourcesPerTarget caps the `by` list per stale entry.
+type InvalidationConfig struct {
+	StaleTime           int64
+	StaleMaxEntries     int
+	MaxSourcesPerTarget int
+}
+
+type requestResult struct {
+	body   []byte
+	status int
+	resp   *http.Response
+}
+
+// requestBody is one request payload. JSON values and byte payloads can be
+// sent again on an auth retry; a Reader cannot.
+type requestBody struct {
+	json        any
+	hasJSON     bool
+	raw         []byte
+	hasRaw      bool
+	reader      io.Reader
+	contentType string
+}
+
+func noBody() requestBody { return requestBody{} }
+
+func jsonBody(v any) requestBody { return requestBody{json: v, hasJSON: true} }
+
+func readerBody(r io.Reader, contentType string) requestBody {
+	return requestBody{reader: r, contentType: contentType}
+}
+
+func formBody(values url.Values) requestBody {
+	return requestBody{raw: []byte(values.Encode()), hasRaw: true, contentType: "application/x-www-form-urlencoded"}
+}
+
+func rawBody(raw []byte, contentType string) requestBody {
+	return requestBody{raw: raw, hasRaw: true, contentType: contentType}
+}
+
+// setHeaderValue sets a header parameter: nil and nil pointers are skipped,
+// slices are joined with commas.
+func setHeaderValue(h map[string]string, name string, v any) {
+	var q queryList
+	q.set(name, v)
+	if len(q) == 0 {
+		return
+	}
+	values := make([]string, 0, len(q))
+	for _, p := range q {
+		values = append(values, p.value)
+	}
+	h[name] = strings.Join(values, ",")
+}
+
+// hasHeader reports whether h has name in any casing.
+func hasHeader(h map[string]string, name string) bool {
+	for k := range h {
+		if strings.EqualFold(k, name) {
+			return true
+		}
+	}
+	return false
+}
+
+func (b requestBody) present() bool { return b.hasJSON || b.hasRaw || b.reader != nil }
+
+func (b requestBody) replayable() bool { return b.reader == nil }
+
+// bytes returns the encoded payload for JSON and raw bodies.
+func (b requestBody) bytes() ([]byte, error) {
+	if b.hasRaw {
+		return b.raw, nil
+	}
+	if b.hasJSON {
+		encoded, err := json.Marshal(b.json)
+		if err != nil {
+			return nil, fmt.Errorf("honey: marshal body: %w", err)
+		}
+		return encoded, nil
+	}
+	return nil, nil
+}
+
+// FilePart is one file in a multipart/form-data upload. The SDK reads Data
+// fully before sending, so the request can be retried after an auth refresh.
+type FilePart struct {
+	Filename    string
+	ContentType string
+	Data        io.Reader
+}
+
+type multipartField struct {
+	name  string
+	value string
+	file  *FilePart
+}
+
+func textField(name string, value any) multipartField {
+	return multipartField{name: name, value: formatQueryValue(value)}
+}
+
+func fileField(name string, file FilePart) multipartField {
+	return multipartField{name: name, file: &file}
+}
+
+func multipartBody(fields []multipartField) (requestBody, error) {
+	var buf bytes.Buffer
+	w := multipart.NewWriter(&buf)
+	for _, f := range fields {
+		if f.file == nil {
+			if err := w.WriteField(f.name, f.value); err != nil {
+				return requestBody{}, err
+			}
+			continue
+		}
+		h := make(textproto.MIMEHeader)
+		filename := f.file.Filename
+		if filename == "" {
+			filename = f.name
+		}
+		h.Set("Content-Disposition", fmt.Sprintf(`form-data; name=%s; filename=%s`, strconv.Quote(f.name), strconv.Quote(filename)))
+		ct := f.file.ContentType
+		if ct == "" {
+			ct = "application/octet-stream"
+		}
+		h.Set("Content-Type", ct)
+		part, err := w.CreatePart(h)
+		if err != nil {
+			return requestBody{}, err
+		}
+		if f.file.Data != nil {
+			if _, err := io.Copy(part, f.file.Data); err != nil {
+				return requestBody{}, err
+			}
+		}
+	}
+	if err := w.Close(); err != nil {
+		return requestBody{}, err
+	}
+	return requestBody{raw: buf.Bytes(), hasRaw: true, contentType: w.FormDataContentType()}, nil
+}
+
+// PathParamError reports a path parameter that is missing, or that would
+// change the request path once a URL parser normalizes it ("", "." and "..").
+type PathParamError struct {
+	Name    string
+	Value   string
+	Missing bool
+}
+
+func (e *PathParamError) Error() string {
+	if e.Missing {
+		return "Missing path param: " + e.Name
+	}
+	return fmt.Sprintf("Invalid path param %q: %q is not a path segment", e.Name, e.Value)
+}
+
+func percentEncode(s string, keep func(c byte) bool, spaceAsPlus bool) string {
+	const hex = "0123456789ABCDEF"
+	var b strings.Builder
+	for i := 0; i < len(s); i++ {
+		c := s[i]
+		switch {
+		case (c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z') || (c >= '0' && c <= '9') || keep(c):
+			b.WriteByte(c)
+		case c == ' ' && spaceAsPlus:
+			b.WriteByte('+')
+		default:
+			b.WriteByte('%')
+			b.WriteByte(hex[c>>4])
+			b.WriteByte(hex[c&0x0f])
+		}
+	}
+	return b.String()
+}
+
+// escapePathSegment encodes like JavaScript's encodeURIComponent, so every
+// SDK language (and the TypeScript client) sends the same path bytes.
+func escapePathSegment(s string) string {
+	return percentEncode(s, func(c byte) bool { return strings.IndexByte("-_.!~*'()", c) >= 0 }, false)
+}
+
+// escapeQueryComponent encodes like URLSearchParams (space becomes '+').
+func escapeQueryComponent(s string) string {
+	return percentEncode(s, func(c byte) bool { return strings.IndexByte("*-._", c) >= 0 }, true)
+}
+
+func encodeSegmentValue(name, value string) (string, error) {
+	if value == "" || value == "." || value == ".." {
+		return "", &PathParamError{Name: name, Value: value}
+	}
+	return escapePathSegment(value), nil
+}
+
+// expandPath fills a path template, segment by segment, with the same grammar
+// as the TypeScript client: `:name` (or `:name?`) takes a whole segment,
+// `*name` (or `*`) as the last segment takes the rest of the path, `{name}`
+// may appear anywhere inside a segment. Values are encoded; values that a URL
+// parser would collapse ("", ".", "..") are rejected.
+func expandPath(template string, params map[string]string) (string, error) {
+	segments := strings.Split(template, "/")
+	out := make([]string, 0, len(segments))
+	for i, seg := range segments {
+		switch {
+		case len(seg) > 1 && seg[0] == ':':
+			optional := strings.HasSuffix(seg, "?")
+			name := strings.TrimSuffix(seg[1:], "?")
+			if !optional {
+				name = seg[1:]
+			}
+			value, ok := params[name]
+			if !ok {
+				if optional {
+					continue
+				}
+				return "", &PathParamError{Name: name, Missing: true}
+			}
+			enc, err := encodeSegmentValue(name, value)
+			if err != nil {
+				return "", err
+			}
+			out = append(out, enc)
+		case len(seg) > 0 && seg[0] == '*' && i == len(segments)-1:
+			name := "*"
+			if len(seg) > 1 {
+				name = seg[1:]
+			}
+			value, ok := params[name]
+			if !ok {
+				if len(seg) == 1 {
+					out = append(out, "")
+					continue
+				}
+				return "", &PathParamError{Name: name, Missing: true}
+			}
+			if value == "" {
+				out = append(out, "")
+				continue
+			}
+			parts := strings.Split(value, "/")
+			for j, part := range parts {
+				enc, err := encodeSegmentValue(name, part)
+				if err != nil {
+					return "", err
+				}
+				parts[j] = enc
+			}
+			out = append(out, strings.Join(parts, "/"))
+		default:
+			var b strings.Builder
+			rest := seg
+			for {
+				open := strings.IndexByte(rest, '{')
+				end := -1
+				if open >= 0 {
+					end = strings.IndexByte(rest[open:], '}')
+				}
+				if open < 0 || end < 0 || strings.ContainsRune(rest[open+1:open+end], '{') {
+					b.WriteString(rest)
+					break
+				}
+				name := rest[open+1 : open+end]
+				value, ok := params[name]
+				if !ok {
+					return "", &PathParamError{Name: name, Missing: true}
+				}
+				enc, err := encodeSegmentValue(name, value)
+				if err != nil {
+					return "", err
+				}
+				b.WriteString(rest[:open])
+				b.WriteString(enc)
+				rest = rest[open+end+1:]
+			}
+			out = append(out, b.String())
+		}
+	}
+	return strings.Join(out, "/"), nil
+}
+
+// queryPair is one key=value in send order.
+type queryPair struct {
+	key   string
+	value string
+}
+
+type queryList []queryPair
+
+// set appends v under key: nil and nil pointers are skipped, slices repeat the key.
+func (q *queryList) set(key string, v any) {
+	rv := reflect.ValueOf(v)
+	for rv.IsValid() && (rv.Kind() == reflect.Pointer || rv.Kind() == reflect.Interface) {
+		if rv.IsNil() {
+			return
+		}
+		rv = rv.Elem()
+	}
+	if !rv.IsValid() {
+		return
+	}
+	if (rv.Kind() == reflect.Slice || rv.Kind() == reflect.Array) && rv.Type().Elem().Kind() != reflect.Uint8 {
+		for i := 0; i < rv.Len(); i++ {
+			q.set(key, rv.Index(i).Interface())
+		}
+		return
+	}
+	*q = append(*q, queryPair{key: key, value: formatQueryValue(rv.Interface())})
+}
+
+func (q queryList) encode() string {
+	parts := make([]string, 0, len(q))
+	for _, p := range q {
+		parts = append(parts, escapeQueryComponent(p.key)+"="+escapeQueryComponent(p.value))
+	}
+	return strings.Join(parts, "&")
+}
+
+// formatQueryValue renders a scalar the way every SDK language does: strings
+// as-is, booleans as true/false, numbers in shortest decimal form, anything
+// else as JSON.
+func formatQueryValue(v any) string {
+	rv := reflect.ValueOf(v)
+	switch rv.Kind() {
+	case reflect.String:
+		return rv.String()
+	case reflect.Bool:
+		return strconv.FormatBool(rv.Bool())
+	case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
+		return strconv.FormatInt(rv.Int(), 10)
+	case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64:
+		return strconv.FormatUint(rv.Uint(), 10)
+	case reflect.Float32, reflect.Float64:
+		return formatFloatJS(rv.Float())
+	}
+	encoded, err := json.Marshal(v)
+	if err != nil {
+		return fmt.Sprint(v)
+	}
+	return string(encoded)
+}
+
+// formatFloatJS renders a float like JavaScript's Number#toString.
+func formatFloatJS(f float64) string {
+	switch {
+	case math.IsNaN(f):
+		return "NaN"
+	case math.IsInf(f, 1):
+		return "Infinity"
+	case math.IsInf(f, -1):
+		return "-Infinity"
+	case f == 0:
+		return "0"
+	}
+	abs := math.Abs(f)
+	if abs >= 1e-6 && abs < 1e21 {
+		return strconv.FormatFloat(f, 'f', -1, 64)
+	}
+	s := strconv.FormatFloat(f, 'e', -1, 64)
+	mantissa, exp, _ := strings.Cut(s, "e")
+	n, _ := strconv.Atoi(exp)
+	sign := "+"
+	if n < 0 {
+		sign = "-"
+		n = -n
+	}
+	return mantissa + "e" + sign + strconv.Itoa(n)
+}
+
+// buildURL joins base and an already-escaped path, keeping the base path and
+// base query, then appends query pairs.
+func buildURL(baseURL, path string, query queryList) (string, error) {
+	base, err := url.Parse(baseURL)
+	if err != nil {
+		return "", err
+	}
+	if base.Scheme == "" || base.Host == "" {
+		return "", fmt.Errorf("honey: base URL %q needs a scheme and host", baseURL)
+	}
+	if !strings.HasPrefix(path, "/") {
+		path = "/" + path
+	}
+	out := *base
+	out.Fragment = ""
+	out.RawFragment = ""
+	joined := strings.TrimRight(base.EscapedPath(), "/") + path
+	unescaped, err := url.PathUnescape(joined)
+	if err != nil {
+		return "", err
+	}
+	out.Path = unescaped
+	out.RawPath = joined
+	extra := query.encode()
+	switch {
+	case out.RawQuery == "":
+		out.RawQuery = extra
+	case extra != "":
+		out.RawQuery = out.RawQuery + "&" + extra
+	}
+	return out.String(), nil
+}
+
+// doRequest executes an HTTP request, injects auth, merges headers, fires
+// OnRequest/OnResponse hooks in declaration order, handles OnAuthExpired retry
+// on 401, and wraps context cancellation errors. Emits OnLog lifecycle entries
+// (request_start once at entry, response_received once for the final response,
+// error on terminal failure) — matching TS/Python behavior where retry rounds
+// do not double-emit.
+func doRequest(
+	ctx context.Context,
+	cfg Config,
+	method string,
+	path string,
+	query queryList,
+	body requestBody,
+	callHeaders map[string]string,
+	operation string,
+	requestMeta *RequestMeta,
+) (result *requestResult, err error) {
+	start := time.Now()
+	defer func() {
+		if err != nil {
+			emitLog(cfg, LogEntry{
+				Level:      "error",
+				Event:      "error",
+				Operation:  operation,
+				DurationMs: time.Since(start).Milliseconds(),
+				Status:     errStatus(err),
+				Err:        err,
+			})
+		}
+	}()
+
+	if ctx.Err() != nil {
+		return nil, fmt.Errorf("honey: request canceled: %w", ctx.Err())
+	}
+	if cfg.Timeout > 0 {
+		var cancel context.CancelFunc
+		ctx, cancel = context.WithTimeout(ctx, cfg.Timeout)
+		defer cancel()
+	}
+
+	emitLog(cfg, LogEntry{
+		Level:     "debug",
+		Event:     "request_start",
+		Operation: operation,
+	})
+
+	token := cfg.auth.current(cfg)
+	result, err = executeRequest(ctx, cfg, method, path, query, body, callHeaders, token, false, requestMeta)
+	if err != nil {
+		return nil, err
+	}
+
+	if result.status == 401 && cfg.OnAuthExpired != nil && body.replayable() {
+		newToken, authErr := cfg.auth.refresh(ctx, cfg, token)
+		if authErr != nil {
+			err = fmt.Errorf("honey: OnAuthExpired failed: %w", authErr)
+			return nil, err
+		}
+		if newToken != "" {
+			result, err = executeRequest(ctx, cfg, method, path, query, body, callHeaders, newToken, true, requestMeta)
+			if err != nil {
+				return nil, err
+			}
+		}
+	}
+
+	status := result.status
+	level := "info"
+	if status >= 400 {
+		level = "warn"
+	}
+	emitLog(cfg, LogEntry{
+		Level:      level,
+		Event:      "response_received",
+		Operation:  operation,
+		DurationMs: time.Since(start).Milliseconds(),
+		Status:     &status,
+	})
+
+	if err2 := raiseForStatus(result.resp, result.body); err2 != nil {
+		err = err2
+		return nil, err
+	}
+
+	return result, nil
+}
+
+func wrapTransportError(ctx context.Context, err error) error {
+	if ctx.Err() != nil {
+		if errors.Is(ctx.Err(), context.DeadlineExceeded) {
+			return fmt.Errorf("honey: request timed out: %w", ctx.Err())
+		}
+		if errors.Is(ctx.Err(), context.Canceled) {
+			return fmt.Errorf("honey: request canceled: %w", ctx.Err())
+		}
+		return fmt.Errorf("honey: context error: %w", ctx.Err())
+	}
+	return fmt.Errorf("honey: http do: %w", err)
+}
+
+// newRequest builds the outgoing request after running the OnRequest hooks.
+func newRequest(
+	ctx context.Context,
+	cfg Config,
+	method string,
+	path string,
+	query queryList,
+	body requestBody,
+	callHeaders map[string]string,
+	bearerToken string,
+	isRetry bool,
+	requestMeta *RequestMeta,
+) (*http.Request, error) {
+	fullURL, err := buildURL(cfg.BaseURL, path, query)
+	if err != nil {
+		return nil, fmt.Errorf("honey: build URL: %w", err)
+	}
+
+	/* Reader bodies stream as-is; RequestContext.Body stays nil for them so hook
+	 * consumers don't try to read or re-hash a single-shot reader. */
+	bodyBytes, err := body.bytes()
+	if err != nil {
+		return nil, err
+	}
+
+	headers := mergeHeaders(cfg, callHeaders, bearerToken, body.present(), body.contentType)
+
+	reqCtx := &RequestContext{
+		Method:  method,
+		URL:     fullURL,
+		Path:    path,
+		Headers: headers,
+		Body:    bodyBytes,
+		IsRetry: isRetry,
+	}
+	if requestMeta != nil {
+		reqCtx.Selector = requestMeta.Selector
+		reqCtx.IsStale = requestMeta.IsStale
+		reqCtx.InvalidatedBy = requestMeta.InvalidatedBy
+	}
+
+	for _, hook := range cfg.OnRequest {
+		if hookErr := hook(reqCtx); hookErr != nil {
+			return nil, fmt.Errorf("honey: OnRequest hook: %w", hookErr)
+		}
+	}
+
+	var reader io.Reader
+	if body.reader != nil {
+		reader = body.reader
+	} else if reqCtx.Body != nil {
+		reader = bytes.NewReader(reqCtx.Body)
+	}
+
+	req, err := http.NewRequestWithContext(ctx, reqCtx.Method, reqCtx.URL, reader)
+	if err != nil {
+		return nil, fmt.Errorf("honey: build request: %w", err)
+	}
+	req.Header = reqCtx.Headers
+	return req, nil
+}
+
+func executeRequest(
+	ctx context.Context,
+	cfg Config,
+	method string,
+	path string,
+	query queryList,
+	body requestBody,
+	callHeaders map[string]string,
+	bearerToken string,
+	isRetry bool,
+	requestMeta *RequestMeta,
+) (*requestResult, error) {
+	req, err := newRequest(ctx, cfg, method, path, query, body, callHeaders, bearerToken, isRetry, requestMeta)
+	if err != nil {
+		return nil, err
+	}
+
+	resp, err := cfg.HTTPClient.Do(req)
+	if err != nil {
+		return nil, wrapTransportError(ctx, err)
+	}
+	defer resp.Body.Close()
+
+	respBody, readErr := readBody(resp.Body, cfg.MaxResponseBytes)
+	if readErr != nil {
+		return nil, wrapTransportError(ctx, readErr)
+	}
+
+	respCtx := &ResponseContext{
+		Status:  resp.StatusCode,
+		Headers: resp.Header,
+		Body:    respBody,
+		IsRetry: isRetry,
+	}
+	if requestMeta != nil {
+		respCtx.Selector = requestMeta.Selector
+		respCtx.IsStale = requestMeta.IsStale
+		respCtx.InvalidatedBy = requestMeta.InvalidatedBy
+	}
+
+	for _, hook := range cfg.OnResponse {
+		if hookErr := hook(respCtx); hookErr != nil {
+			return nil, fmt.Errorf("honey: OnResponse hook: %w", hookErr)
+		}
+	}
+
+	return &requestResult{body: respCtx.Body, status: resp.StatusCode, resp: resp}, nil
+}
+
+// ErrResponseTooLarge is returned when a buffered body exceeds Config.MaxResponseBytes.
+var ErrResponseTooLarge = errors.New("honey: response body exceeds MaxResponseBytes")
+
+func readBody(r io.Reader, limit int64) ([]byte, error) {
+	if limit < 0 {
+		return io.ReadAll(r)
+	}
+	body, err := io.ReadAll(io.LimitReader(r, limit+1))
+	if err != nil {
+		return nil, err
+	}
+	if int64(len(body)) > limit {
+		return nil, ErrResponseTooLarge
+	}
+	return body, nil
+}
+
+// streamClient is the configured client without its overall timeout: an
+// http.Client Timeout also bounds body reads, which would cut every stream.
+func streamClient(cfg Config) *http.Client {
+	c := *cfg.HTTPClient
+	c.Timeout = 0
+	return &c
+}
+
+// openStream sends a streaming request (SSE) through the same URL, header,
+// auth and hook pipeline as a regular request. Non-2xx statuses become typed
+// errors; the caller owns the returned body.
+func openStream(
+	ctx context.Context,
+	cfg Config,
+	method string,
+	path string,
+	query queryList,
+	body requestBody,
+	callHeaders map[string]string,
+) (*http.Response, error) {
+	token := cfg.auth.current(cfg)
+	for attempt := 0; ; attempt++ {
+		req, err := newRequest(ctx, cfg, method, path, query, body, callHeaders, token, attempt > 0, nil)
+		if err != nil {
+			return nil, err
+		}
+		resp, err := streamClient(cfg).Do(req)
+		if err != nil {
+			return nil, wrapTransportError(ctx, err)
+		}
+		if resp.StatusCode == 401 && attempt == 0 && cfg.OnAuthExpired != nil && body.replayable() {
+			errBody, _ := readBody(resp.Body, 64<<10)
+			resp.Body.Close()
+			newToken, authErr := cfg.auth.refresh(ctx, cfg, token)
+			if authErr != nil {
+				return nil, fmt.Errorf("honey: OnAuthExpired failed: %w", authErr)
+			}
+			if newToken == "" {
+				return nil, raiseForStatus(resp, errBody)
+			}
+			token = newToken
+			continue
+		}
+		if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+			defer resp.Body.Close()
+			errBody, _ := readBody(resp.Body, 64<<10)
+			return nil, raiseForStatus(resp, errBody)
+		}
+		return resp, nil
+	}
+}
+
+// authHeaders returns cfg.Headers plus the auth header, for transports that
+// cannot run the full request pipeline (WebSocket dials).
+func authHeaders(cfg Config, extra map[string]string) http.Header {
+	return mergeHeaders(cfg, extra, cfg.auth.current(cfg), false, "")
+}
+
+// mergeHeaders builds the final http.Header for a request by merging in order:
+// config Headers → call Headers (per-call wins per key, case-insensitively) →
+// Content-Type when hasBody → Authorization when bearerToken non-empty →
+// X-Request-Id when absent (OnRequest hooks may still overwrite). Returned
+// header is owned by the caller and may be mutated freely (e.g. by OnRequest
+// hooks). contentType is the explicit Content-Type for the request body; when
+// empty and hasBody is true, defaults to application/json.
+func mergeHeaders(
+	cfg Config,
+	callHeaders map[string]string,
+	bearerToken string,
+	hasBody bool,
+	contentType string,
+) http.Header {
+	h := http.Header{}
+	if hasBody {
+		ct := contentType
+		if ct == "" {
+			ct = "application/json"
+		}
+		h.Set("Content-Type", ct)
+	}
+	for _, k := range sortedKeys(cfg.Headers) {
+		h.Set(k, cfg.Headers[k])
+	}
+	for _, k := range sortedKeys(callHeaders) {
+		h.Set(k, callHeaders[k])
+	}
+	if bearerToken != "" {
+		name := cfg.AuthHeaderName
+		if name == "" {
+			name = "Authorization"
+		}
+		prefix := cfg.AuthHeaderPrefix
+		if prefix == "" {
+			prefix = "Bearer "
+		}
+		h.Set(name, prefix+bearerToken)
+	}
+	if h.Get("X-Request-Id") == "" {
+		h.Set("X-Request-Id", newUUIDv4())
+	}
+	return h
+}
+
+func sortedKeys(m map[string]string) []string {
+	keys := make([]string, 0, len(m))
+	for k := range m {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+	return keys
+}
+
+func unmarshalBody[T any](body []byte) (*T, error) {
+	if len(body) == 0 {
+		return nil, nil
+	}
+	var out T
+	if err := json.Unmarshal(body, &out); err != nil {
+		return nil, fmt.Errorf("honey: unmarshal response: %w", err)
+	}
+	return &out, nil
+}
+
+// newUUIDv4 returns a freshly generated RFC 4122 §4.4 random UUID string.
+// Uses crypto/rand for entropy; sets version (4) and variant (10xx) bits per
+// the spec, then formats canonical 8-4-4-4-12 lower-case hex. Zero external
+// deps so generated SDKs add no third-party rows to consumer go.sum files.
+func newUUIDv4() string {
+	var b [16]byte
+	if _, err := rand.Read(b[:]); err != nil {
+		/* crypto/rand.Read is documented to never return non-nil err on supported
+		 * platforms; if it does the OS entropy source is broken — silent fallback
+		 * would corrupt dedupe semantics, so panic mirrors google/uuid. */
+		panic("honey: crypto/rand failed: " + err.Error())
+	}
+	b[6] = (b[6] & 0x0f) | 0x40 /* version 4 */
+	b[8] = (b[8] & 0x3f) | 0x80 /* variant 10xx */
+	const hex = "0123456789abcdef"
+	out := make([]byte, 36)
+	j := 0
+	for i, by := range b {
+		if i == 4 || i == 6 || i == 8 || i == 10 {
+			out[j] = '-'
+			j++
+		}
+		out[j] = hex[by>>4]
+		out[j+1] = hex[by&0x0f]
+		j += 2
+	}
+	return string(out)
+}