appstep

package
v0.10.1 Latest Latest
Warning

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

Go to latest
Published: Oct 16, 2026 License: Apache-2.0 Imports: 6 Imported by: 0

Documentation

Overview

Package appstep defines the steps a request goes through: what a step is, and how it describes itself.

A step is a formal operation: defined once with a name and whether it is public, then run wherever the operation runs (see apptracing). It feeds two things at once — a span in the trace, and context on any error that passes through it — so the operation trail is written once. There is no way to add informal, ad hoc context: context first means formalising the step.

A public step carries a fragment of user-facing text, and appears in the context of an error's response. A private step appears only in the log and the trace. Making a step public later is a change to its definition, never to the code that runs it.

Two types, one per concept: a Def is a step's definition, made once by Define; a Step is one occurrence — a Def and the parameters it ran with. "Step" always means an occurrence, as in "the steps an error passed through".

Every step belongs to a namespace, one per module, and is named by it everywhere — the log, the trace and the context of a response: anfra_cloud.import_dashboard. A library's public steps reach its host's clients as they are, so the qualified name keeps two modules' steps apart without either knowing the other. apperr names its codes by the same namespaces.

This package knows nothing of errors, responses or tracing. A Step describes itself (String and Logged for the log and the trace, Describe for a user); apperr decides how that appears in a response, and apptracing runs steps and attaches them to errors.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Def

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

Def is a step's definition: a handle to it. Only Define makes one.

func Define

func Define(ns Namespace, name string, opts ...Option) Def

Define declares a step of ns. Call it from a package-level var, once per name; a duplicate name in ns, a public template that does not parse, or an empty or repeated Sensitive key panics at startup. Without Public, the step is private.

Names are unique because a public step's qualified name reaches clients, as the step of a context entry, and a client localising its text keys on it.

func (Def) String

func (d Def) String() string

String is the step's qualified name.

type Description

type Description struct {
	Name   string         // the step's qualified name; stable, since a localising client keys on it
	Params map[string]any // only the parameters the template names; nil if none
	Text   string         // the filled template: "import dashboard 'Sales'"
}

Description is how a step describes itself to a user: its public template, filled from the parameters it ran with.

type Namespace

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

Namespace is a module's namespace, for its steps and its error codes (see apperr): a name is unique within it. Only DefineNamespace makes one.

func DefineNamespace

func DefineNamespace(name string) Namespace

DefineNamespace declares a module's namespace. Call it once per module, from a package-level var. A name is snake_case, as step and code names are — anfra_cloud — so a qualified name splits at its first dot; another name, or a duplicate, panics at startup.

func (Namespace) String

func (ns Namespace) String() string

String is the namespace's name. The zero Namespace has none.

type Option

type Option func(*config)

Option configures a step at its definition.

func Public

func Public(template string) Option

Public makes a step appear in the context of an error's response, as template filled from the step's parameters: a lowercase verb phrase naming the attempt, with no punctuation — "import dashboard {name}". It names what was being done, never why it failed.

func Sensitive

func Sensitive(keys ...string) Option

Sensitive declares parameters, by key, whose values must not reach telemetry — an email, a name a person typed. Every run of the step redacts them from the log form and the trace, so no call site can forget; they may still appear in the user-facing description, since they came from the user.

type Step

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

Step is one occurrence of a step: its definition and the parameters it ran with. It is what an error holds for each step it passed through.

func NewStep

func NewStep(def Def, kv ...any) Step

NewStep is an occurrence of def with kv, key/value pairs as in slog. Which of them are sensitive is the definition's declaration (Sensitive), not the caller's. A malformed pair is kept, visibly, under a bad key, rather than panicking inside a request.

func (Step) Describe

func (s Step) Describe() (Description, bool)

Describe returns s's description, or false when its definition is private, or when its template names a parameter s was not given: never shown half-filled. String values are quoted in single quotes; others render with %v.

func (Step) Logged

func (s Step) Logged() iter.Seq2[string, any]

Logged yields the parameters as the log and the trace see them, in the order given, with sensitive values redacted.

func (Step) Name

func (s Step) Name() string

Name is the step's qualified name.

func (Step) String

func (s Step) String() string

String is the log form, with sensitive values redacted: anfra_cloud.import_dashboard(name=Sales, owner=[redacted]).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL