proxy

type Pipeline struct {
	Limiter   *pkgratelimit.Limiter
	Lifecycle *lifecycle.Registry
	Client    *http.Client
	Logger    *slog.Logger
}

type Request struct {
	// Method + Path are the inbound HTTP method and path appended to
	// HostBaseURL when building the upstream URL. Path includes the
	// leading slash (e.g. "/v1/messages").
	Method string
	Path   string

	// Body is the inbound request body. Streamed through to upstream
	// verbatim; the proxy does not buffer it. Transport-layer code that
	// wants to inspect the body (for usage stamping, deep validation,
	// etc.) should ReadAll first and pass a *bytes.Reader here — proxy
	// stays shape-blind either way.
	Body io.Reader

	// ContentLength is the inbound request's Content-Length, applied to
	// the upstream request explicitly because a non-seekable streamed Body
	// gives http.NewRequest no length to infer — without it the forward
	// degrades to chunked transfer. <= 0 means unknown.
	ContentLength int64

	// Headers is the inbound header set with relay-internal headers
	// already stripped (X-WR-*, Cookie, hop-by-hop).
	// Authorization is set separately via UpstreamAuth — do not include
	// it here.
	Headers http.Header

	// HostBaseURL is the resolved upstream base URL from the Host row.
	HostBaseURL string

	// UpstreamAuth is the verbatim "Authorization" value the caller
	// supplied (typically "Bearer …"). Forwarded as-is.
	UpstreamAuth string

	// RateScope is the limiter bucket subject — the relay-key hash for
	// authed, the client IP for anonymous. Empty disables limiting.
	RateScope string
	// Rules is the resolved rule set (system-owned for proxy mode).
	Rules []pkgratelimit.Rule

	// Extractor parses the upstream response body for usage logging.
	// nil disables extraction (post-flight still commits the reservation).
	Extractor TokenExtractor

	// ModelName is for logging only — proxy mode does not consult the
	// catalog Model row.
	ModelName string

	// Lifecycle is the per-request shared context, constructed by the
	// handler before Run. Post-flight observers see it via the registered
	// lifecycle observers (Finalize). Optional — nil skips observer dispatch.
	Lifecycle *lifecycle.Context
}

type Result struct {
	Status  int
	Headers http.Header
	// Body MUST be Closed by the caller. Closing triggers the post-
	// flight goroutine (if it hasn't run already).
	Body io.ReadCloser
}

type TokenExtractor interface {
	ExtractTokens(body []byte) sdkusage.Tokens
}