Documentation
¶
Overview ¶
Package render turns a (masked) product result into the text an agent sees, within the caps of a profile: a table (TSV or JSON) or any typed JSON value. Control and bidirectional characters are escaped, invalid UTF-8 is replaced, NULL is "NULL" (null in JSON), binary values are "<bytes:N>" and times ISO 8601.
Cells are cut while they are converted, so a huge value never costs more than its cap in output.
Index ¶
- Constants
- Variables
- func CapText(s string, maxChars int, jsonMode bool) (string, bool)
- func Render(w io.Writer, t Table, l Caps, format string) error
- func Text(v any) string
- func Value(w io.Writer, v any, l Caps) error
- type Caps
- type Cells
- type Line
- type MaskedScreen
- type Masking
- type Part
- type ScreenSource
- type Table
Constants ¶
const ( FormatTSV = "tsv" FormatJSON = "json" )
Formats.
const TouchedColumn = "personal_column"
TouchedColumn is the kind of personal data reported for a value masked because its column looks personal.
Variables ¶
var DefaultCaps = Caps{MaxRows: 200, MaxCellChars: 200, MaxOutputBytes: 65_536}
DefaultCaps are the caps of an unset field.
var ErrOutputCap = errors.New("render: the result is over the output cap")
ErrOutputCap means a value encodes to more than Caps.MaxOutputBytes: nothing is written. The product pages or narrows its result.
var ErrUnmasked = errors.New("render: screen not built by MaskScreen")
ErrUnmasked is the error of a MaskedScreen that MaskScreen did not build.
Functions ¶
func Render ¶
Render writes t to w in format "tsv" (the default when empty) or "json". Rows beyond MaxRows are dropped and reported as truncated; rows that would push the output past MaxOutputBytes are dropped with a marker.
func Text ¶
Text is the display form of a non-nil value: bytes as <bytes:N>, times in RFC 3339, floats with NaN and ±Infinity spelled out.
func Value ¶
Value writes v as one line of JSON: every string, object keys included, escaped and cut at Caps.MaxCellChars characters (as a table cell in JSON mode); numbers, booleans and nulls keep their JSON type. The output is at most Caps.MaxOutputBytes, or ErrOutputCap and nothing written. MaxRows does not apply: a product bounds its own lists.
Types ¶
type Caps ¶
type Caps struct {
MaxRows int
MaxCellChars int
MaxOutputBytes int
// CutNote is the footer line that tells how many cells were cut; nil
// gives the default wording.
CutNote func(cells, maxChars int) string
}
Caps bound an output. Zero or negative fields take the defaults (DefaultCaps).
type Cells ¶
Cells is the TSV rendering of a table split into cells, with the same caps as Render: the header labels, the rows shown and the lines after them (cut marker, row count).
type MaskedScreen ¶ added in v0.3.0
type MaskedScreen struct {
// contains filtered or unexported fields
}
MaskedScreen is an approval screen that went through MaskScreen: the only form in which a screen may leave the lock (to the hub, in a ticket). It has no exported field and no other constructor; its zero value is not a screen (Valid is false and it does not encode).
func MaskScreen ¶ added in v0.3.0
func MaskScreen(src ScreenSource, m Masking) MaskedScreen
MaskScreen masks src: every value whose column looks personal is masked whole, and the detectors mask what they find in values, structure, header, note and warnings alike. The structure of the request stays visible.
func (MaskedScreen) MarshalJSON ¶ added in v0.3.0
func (m MaskedScreen) MarshalJSON() ([]byte, error)
MarshalJSON encodes the masked screen as a ticket.Screen; a screen MaskScreen did not build does not encode.
func (MaskedScreen) Screen ¶ added in v0.3.0
func (m MaskedScreen) Screen() ticket.Screen
Screen is the masked screen, for a ticket (a copy).
func (MaskedScreen) Touched ¶ added in v0.3.0
func (m MaskedScreen) Touched() []string
Touched names the kinds of personal data masked (ticket.PII.Touched): detector names and TouchedColumn, sorted.
func (MaskedScreen) Valid ¶ added in v0.3.0
func (m MaskedScreen) Valid() bool
Valid reports whether MaskScreen built m.
type Masking ¶ added in v0.3.0
type Masking struct {
// Detectors find personal values in any text (pii.Detectors); none
// is every detector (pii.AllDetectors), never no detection.
Detectors []pii.Detector
// Personal reports a personal column; nil is pii.LooksPersonalColumn.
Personal func(column, typ string) bool
}
Masking says what is personal on a screen.
type Part ¶ added in v0.3.0
type Part struct {
Text string
// Value marks a value; structure is masked only where a detector finds
// personal data in it.
Value bool
// Column and ColumnType name where the value goes or comes from ("email",
// "varchar"); "" when unknown.
Column, ColumnType string
}
A Part is one piece of a line of an approval screen: structure (keywords, identifiers, operators, which stay visible) or a value (a literal, a parameter, a field of a message), with the column or field it belongs to when the product knows it.
type ScreenSource ¶ added in v0.3.0
type ScreenSource struct {
// Header names the request ("db / shop · tier read").
Header string
// Note is the agent's one-line reason (untrusted).
Note string
// Body are the lines of the request; Warnings are shown in red.
Body []Line
Warnings []string
// Red frames the screen in red outside production too.
Red bool
}
ScreenSource is an approval screen as a product draws it, before masking.
type Table ¶
type Table struct {
Columns []string
Rows [][]any
Truncated bool // more rows exist beyond the producer's own cap
Affected int64
// Cut marks the cells (row, column) the producer already cut while
// reading them; they count in the cut-cells note.
Cut map[[2]int]bool
}
Table is a tabular result: column labels and rows of values. A table without columns reports Affected rows instead (a write).