response

package
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Sep 22, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

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

Constants

This section is empty.

Variables

This section is empty.

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.

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.