outputlimit

Documentation

Overview

Package outputlimit renders bounded output without splitting UTF-8 or CRLF.

Index

• Constants
• Variables
• func BoundJSON(projected map[string]any, grant int, policy Policy, fallback JSONFallback) (map[string]any, int, error)
• func Marker(reason string, keptBytes, origBytes, keptLines, origLines int) string
• type Budget
  • func NewBudget(perSession int) *Budget
  • func (b *Budget) Consume(sessionID string, reservationID uint64, emitted int)
  • func (b *Budget) Report(sessionID string) (used, limit int)
  • func (b *Budget) Reserve(sessionID string, want int) Reservation
  • func (b *Budget) Reset(sessionID string)
• type JSONFallback
• type Policy
  • func Defaults() Policy
  • func (p Policy) Apply(input string) (string, Report)
  • func (p Policy) ApplyLines(lines []string, firstLineNumber int) (string, Report)
• type Report
• type Reservation
• type Writer
  • func NewWriter(policy Policy) (*Writer, error)
  • func (w *Writer) Reset()
  • func (w *Writer) Result() (string, Report)
  • func (w *Writer) String() (string, Report)
  • func (w *Writer) Write(p []byte) (int, error)

Constants

const (
	ReasonBytes      = "bytes"
	ReasonLines      = "lines"
	ReasonLineLength = "line_length"
	ReasonBudget     = "budget"
	ReasonFile       = "file"
)

const DefaultPerSession = 400000

const MinimumBudgetGrant = 2000

Variables

var (
	ErrInvalidLimit    = errors.New("outputlimit: invalid limit")
	ErrCounterOverflow = errors.New("outputlimit: counter overflow")
)

Functions

func BoundJSON

func BoundJSON(projected map[string]any, grant int, policy Policy, fallback JSONFallback) (map[string]any, int, error)

BoundJSON serializes a result and returns a complete JSON-safe value whose final encoding fits both the call grant and policy. The returned byte count is the size consumers must charge to the session budget.

func Marker

func Marker(reason string, keptBytes, origBytes, keptLines, origLines int) string

Marker returns the normative output-elision marker. Unknown reasons fail soft because marker construction is also used while reading foreign data.

Types

type Budget

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

Budget coordinates cumulative rendered output independently per session.

func NewBudget

func NewBudget(perSession int) *Budget

NewBudget constructs a per-session budget. Non-positive values use the package default.

func (*Budget) Consume

func (b *Budget) Consume(sessionID string, reservationID uint64, emitted int)

Consume settles one reservation with the bytes actually emitted.

func (*Budget) Report

func (b *Budget) Report(sessionID string) (used, limit int)

Report returns consumed bytes and the configured per-session limit.

func (*Budget) Reserve

func (b *Budget) Reserve(sessionID string, want int) Reservation

Reserve returns and records the cap available to one tool call.

func (*Budget) Reset

func (b *Budget) Reset(sessionID string)

Reset restores a session's full budget and drops outstanding reservations.

type JSONFallback

type JSONFallback func(text string, report Report) map[string]any

JSONFallback projects truncated JSON text into the consumer's wire shape. BoundJSON still owns the byte accounting and normative truncation report.

type Policy

type Policy struct {
	MaxBytes     int     `json:"max_bytes"`
	MaxLines     int     `json:"max_lines"`
	MaxLineBytes int     `json:"max_line_bytes"`
	HeadFraction float64 `json:"head_fraction"`
}

Policy controls source content retained in rendered output. Non-positive limits are disabled.

func Defaults

func Defaults() Policy

Defaults returns the default output policy.

func (Policy) Apply

func (p Policy) Apply(input string) (string, Report)

Apply applies line-body elision before aggregate byte and line selection.

func (Policy) ApplyLines

func (p Policy) ApplyLines(lines []string, firstLineNumber int) (string, Report)

ApplyLines renders logical lines separated by newlines. The first line number is reserved for consumers that annotate omitted source ranges.

type Report

type Report struct {
	Truncated     bool   `json:"truncated"`
	Reason        string `json:"reason"`
	OriginalBytes int    `json:"original_bytes"`
	OriginalLines int    `json:"original_lines"`
	KeptBytes     int    `json:"kept_bytes"`
	KeptLines     int    `json:"kept_lines"`
}

Report describes source content removed from output. Marker bytes and aggregate separator bytes are not source content and are excluded.

type Reservation

type Reservation struct {
	ID    uint64
	Grant int
}

Reservation identifies one outstanding budget grant. IDs are unique within a Budget so concurrent calls can settle in completion order.

type Writer

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

Writer retains bounded head and tail samples from a byte stream.

func NewWriter

func NewWriter(policy Policy) (*Writer, error)

NewWriter constructs a writer whose dynamic buffers never exceed twice the policy's aggregate byte limit when MaxBytes is positive. A zero MaxBytes preserves the policy's unlimited-output meaning.

func (*Writer) Reset

func (w *Writer) Reset()

Reset discards the captured stream and accounting state.

func (*Writer) Result

func (w *Writer) Result() (string, Report)

Result is an alias for String.

func (*Writer) String

func (w *Writer) String() (string, Report)

String renders the captured stream and its truncation report.

func (*Writer) Write

func (w *Writer) Write(p []byte) (int, error)

Write implements io.Writer. Counter overflow rejects the whole chunk.