response

Documentation

Overview

Package response holds public response, status, buffered transport response, and shared response metric payload contracts.

The stable core is:

• Status / StatusCoder
• Writer
• Response / Compressed
• Buffered as the transport-ready convenience implementation
• Metric payload shapes

Some helper APIs remain public for compatibility, but they should be treated as helper surface rather than the governing center of the package.

Index

• func ErrorBody(err error) (any, bool)
• func ErrorStatusCode(err error, fallback int) int
• func ExpandSQL(SQL string, args []interface{}) string
• type BodyError
• type Buffered
  • func NewBuffered(options ...Option) *Buffered
  • func (b *Buffered) Body() io.Reader
  • func (b *Buffered) CompressionType() string
  • func (b *Buffered) Headers() http.Header
  • func (b *Buffered) SetStatusCode(status int)
  • func (b *Buffered) Size() int
  • func (b *Buffered) StatusCode() int
  • func (b *Buffered) Write(data []byte) (int, error)
• type CacheStats
  • func (s *CacheStats) SetCreatedTime(value *time.Time)
• type Compressed
• type Error
  • func (e *Error) Error() string
  • func (e *Error) ResponseBody() any
  • func (e *Error) StatusCode() int
  • func (e *Error) Unwrap() error
• type Metric
  • func (m *Metric) HideSQL() *Metric
  • func (m *Metric) Name() string
  • func (m *Metric) ParametrizedSQL() []*ParametrizedSQL
  • func (m *Metric) SQL() string
• type Metrics
  • func (m *Metrics) Append(metrics ...*Metric)
  • func (m Metrics) HideMetrics() Metrics
  • func (m Metrics) Lookup(viewName string) *Metric
  • func (m Metrics) ParametrizedSQL() []*ParametrizedSQL
  • func (m Metrics) SQL() string
  • func (m Metrics) ToSpans(ownerID *string) []*tracing.Span
• type Option
  • func WithBuffer(buffer *bytes.Buffer) Option
  • func WithBytes(data []byte) Option
  • func WithCompressionType(compression string) Option
  • func WithCompressions(compression string) Option
  • func WithHeader(name, value string) Option
  • func WithHeaders(header http.Header) Option
  • func WithSize(size int) Option
  • func WithStatusCode(statusCode int) Option
• type Options
  • func (o *Options) AdjustStatusCode(candidates ...any)
  • func (o *Options) Append(opts ...Option)
  • func (o *Options) Options() Options
• type ParametrizedSQL
• type Response
• type SQLExecution
  • func (s *SQLExecution) SetError(err error)
  • func (s *SQLExecution) ToSpan(viewName string) *tracing.Span
• type SQLExecutions
  • func (s *SQLExecutions) Append(executions ...*SQLExecution)
• type Status
• type StatusCoder
• type Writer

Functions

func ErrorBody

func ErrorBody(err error) (any, bool)

ErrorBody follows ordinary wrapping (including errors.Join). A true result is explicit even when the returned body is nil.

func ErrorStatusCode

func ErrorStatusCode(err error, fallback int) int

ErrorStatusCode unwraps err and returns its status code when present.

func ExpandSQL

func ExpandSQL(SQL string, args []interface{}) string

Types

type BodyError

type BodyError interface {
	error
	StatusCoder
	ResponseBody() any
}

BodyError explicitly supplies a client-visible error body. The body is not merged with internal diagnostics; nil deliberately means JSON null.

type Buffered

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

Buffered is the stable in-memory convenience implementation of Response. It stays public because handlers and runtimes may need one transport-ready response value without depending on a specific HTTP framework.

func NewBuffered

func NewBuffered(options ...Option) *Buffered

func (*Buffered) Body

func (b *Buffered) Body() io.Reader

func (*Buffered) CompressionType

func (b *Buffered) CompressionType() string

func (*Buffered) Headers

func (b *Buffered) Headers() http.Header

func (*Buffered) SetStatusCode

func (b *Buffered) SetStatusCode(status int)

func (*Buffered) Size

func (b *Buffered) Size() int

func (*Buffered) StatusCode

func (b *Buffered) StatusCode() int

func (*Buffered) Write

func (b *Buffered) Write(data []byte) (int, error)

type CacheStats

type CacheStats struct {
	Type           string     `json:"type,omitempty"`
	RecordsCounter int        `json:"recordsCounter,omitempty"`
	Key            string     `json:"key,omitempty"`
	Dataset        string     `json:"dataset,omitempty"`
	Namespace      string     `json:"namespace,omitempty"`
	FoundWarmup    bool       `json:"foundWarmup,omitempty"`
	FoundLazy      bool       `json:"foundLazy,omitempty"`
	ErrorType      string     `json:"errorType,omitempty"`
	ErrorCode      int        `json:"errorCode,omitempty"`
	ExpiryTime     *time.Time `json:"expiryTime,omitempty"`
	CreatedTime    *time.Time `json:"createdTime,omitempty"`
}

func (*CacheStats) SetCreatedTime

func (s *CacheStats) SetCreatedTime(value *time.Time)

SetCreatedTime records a detached timestamp from a native cache entry.

type Compressed

type Compressed interface {
	CompressionType() string
}

Compressed marks a transport response whose body is already encoded.

type Error

type Error struct {
	Code    int   `json:"-"`
	Payload any   `json:"-"`
	Cause   error `json:"-"`
}

Error separates the public status/payload from a private, wrappable cause. Payload may be a typed struct or map; its own JSON tags control empty/null fields. Never place confidential diagnostics in Payload.

func (*Error) Error

func (e *Error) Error() string

func (*Error) ResponseBody

func (e *Error) ResponseBody() any

func (*Error) StatusCode

func (e *Error) StatusCode() int

func (*Error) Unwrap

func (e *Error) Unwrap() error

type Metric

type Metric struct {
	ID         string        `json:"id,omitempty"`
	StartTime  time.Time     `json:"startTime,omitempty"`
	EndTime    time.Time     `json:"endTime,omitempty"`
	View       string        `json:"view,omitempty"`
	Type       string        `json:"type,omitempty"`
	Elapsed    string        `json:"elapsed,omitempty"`
	ElapsedMs  int           `json:"elapsedMs,omitempty"`
	Rows       int           `json:"rows,omitempty"`
	Executions SQLExecutions `json:"executions,omitempty"`
	Error      string        `json:"error,omitempty"`
}

func (*Metric) HideSQL

func (m *Metric) HideSQL() *Metric

func (*Metric) Name

func (m *Metric) Name() string

func (*Metric) ParametrizedSQL

func (m *Metric) ParametrizedSQL() []*ParametrizedSQL

func (*Metric) SQL

func (m *Metric) SQL() string

type Metrics

type Metrics []*Metric

func (*Metrics) Append

func (m *Metrics) Append(metrics ...*Metric)

func (Metrics) HideMetrics

func (m Metrics) HideMetrics() Metrics

func (Metrics) Lookup

func (m Metrics) Lookup(viewName string) *Metric

func (Metrics) ParametrizedSQL

func (m Metrics) ParametrizedSQL() []*ParametrizedSQL

func (Metrics) SQL

func (m Metrics) SQL() string

func (Metrics) ToSpans

func (m Metrics) ToSpans(ownerID *string) []*tracing.Span

type Option

type Option func(r *Buffered)

Option configures a buffered response.

func WithBuffer

func WithBuffer(buffer *bytes.Buffer) Option

func WithBytes

func WithBytes(data []byte) Option

func WithCompressionType

func WithCompressionType(compression string) Option

func WithCompressions

func WithCompressions(compression string) Option

WithCompressions preserves the older option spelling used by existing call sites while keeping the owner under the response transport package.

func WithHeader

func WithHeader(name, value string) Option

func WithHeaders

func WithHeaders(header http.Header) Option

func WithSize

func WithSize(size int) Option

func WithStatusCode

func WithStatusCode(statusCode int) Option

type Options

type Options []Option

Options is a buffered response option list.

func (*Options) AdjustStatusCode

func (o *Options) AdjustStatusCode(candidates ...any)

AdjustStatusCode applies the first available explicit status code candidates.

func (*Options) Append

func (o *Options) Append(opts ...Option)

Append appends options.

func (*Options) Options

func (o *Options) Options() Options

Options returns the underlying list.

type ParametrizedSQL

type ParametrizedSQL struct {
	Query string
	Args  []interface{}
}

type Response

type Response interface {
	StatusCoder
	Body() io.Reader
	Headers() http.Header
	Size() int
	SetStatusCode(int)
}

Response is a transport-ready response that an HTTP surface can write directly without JSON shaping.

type SQLExecution

type SQLExecution struct {
	ID         string        `json:"id,omitempty"`
	ParentID   string        `json:"parentID,omitempty"`
	StartTime  time.Time     `json:"startTime,omitempty"`
	EndTime    time.Time     `json:"endTime,omitempty"`
	SQL        string        `json:"sql,omitempty"`
	Args       []interface{} `json:"args,omitempty"`
	Rows       int           `json:"rows,omitempty"`
	CacheStats *CacheStats   `json:"cacheStats,omitempty"`
	Error      string        `json:"error,omitempty"`
}

func (*SQLExecution) SetError

func (s *SQLExecution) SetError(err error)

func (*SQLExecution) ToSpan

func (s *SQLExecution) ToSpan(viewName string) *tracing.Span

type SQLExecutions

type SQLExecutions []*SQLExecution

func (*SQLExecutions) Append

func (s *SQLExecutions) Append(executions ...*SQLExecution)

type Status

type Status struct {
	Status  string `json:"status,omitempty"`
	Message string `json:"message,omitempty"`
	Error   any    `json:"error,omitempty"`
}

Status is the minimal shared output-status payload contract. It stays intentionally small so runtimes can populate it without pulling response-shaping internals into the public surface.

type StatusCoder

type StatusCoder interface {
	StatusCode() int
}

StatusCoder is the minimal shared error/response contract for surfaces that carry an explicit status code.

type Writer

type Writer interface {
	StatusCode() int
	SetStatusCode(code int)
	AddError(err error)
	AddMetric(metric *Metric)
	Metrics() Metrics
}

Writer is the minimal handler-visible response/status facade. Ownership of final response/meta/status shaping stays with runtime.