Documentation
¶
Overview ¶
Package logutil entity helpers.
These helpers exist to enforce CLAUDE.md convention 18: internal `id INT UNSIGNED` is for FK / JOIN only. Only `public_id BINARY(16)` (UUID v7) may be exposed externally — including in structured logs.
The previous pattern of `slog.Int64("workspace_id", int64(ws.ID))` is forbidden by the forbidigo lint rule; use LogEntity instead.
The lint rule is a nudge, not the boundary. It can only match on the callee name, so it never sees `slog.Any("workspace_id", ws.ID)` nor the loose `logger.Warn(msg, "workspace_id", id)` key/value form. The boundary that actually holds is RedactHandler, which inspects the resolved record: see IsInternalIDKey.
Package logutil provides structured-logging helpers shared across all nodate-flow Go services. The centrepiece is RedactHandler, an slog.Handler wrapper that scrubs secret-looking values before they reach the underlying writer.
Index ¶
- Constants
- Variables
- func IsInternalIDKey(key string) bool
- func LogEntity(name string, publicID uuid.UUID) slog.Attr
- func LogEntityPID(name string, publicID dbtype.PublicID) slog.Attr
- func LogNumber[T numeric](name string, v T) slog.Attr
- func Redact(s string) string
- func RedactJSONFields(s string) string
- func RegisterPrefix(p string)
- type RedactHandler
Constants ¶
const InternalIDPlaceholder = "[REDACTED:internal-id]"
InternalIDPlaceholder replaces the value of any numeric attr whose key names a row id. It is deliberately loud: an operator who sees it knows the call site still has to be moved onto LogEntity.
Variables ¶
var SecretPrefixes = []string{
"sk-ant-",
"sk-",
"sk_live_",
"mcp_",
"pat_",
"rfr_",
"ghp_",
"gho_",
"github_pat_",
"glpat-",
"xoxb-",
"xoxp-",
"AKIA",
"AIza",
"SG.",
"rk_live_",
}
SecretPrefixes is the fixed list of literal prefixes scanned for in strings passed to Redact. The project rule forbids regex, so this list is the single source of truth for prefix-based secret detection.
Add new prefixes via RegisterPrefix at process startup. Order does not matter; the scanner walks every prefix per input.
Functions ¶
func IsInternalIDKey ¶
IsInternalIDKey reports whether an attr key names an internal row id and therefore must not carry a numeric value into a log line.
The predicate is on the key, not the value, because the key is the only thing available at every point the rule has to hold: the call site, the slog.Any escape hatch, the loose key/value form, and the handler. A "_public_id" key is exempt — that is the sanctioned spelling and its value is a UUID string, never a sequence.
The rule is intentionally blunt. A numeric attr under an id-shaped key is either an internal sequence (a leak) or a badly named counter (a naming bug); redacting both is the safe direction, and callers with a genuine number can rename or use LogNumber under a non-id key.
func LogEntity ¶
LogEntity returns a slog.Attr for a domain entity, keyed "<name>_public_id" with the canonical UUID string form as value.
Use this in place of slog.Int64("<name>_id", ...) for any user-facing entity (workspace, task, user, project, page, label, comment, event, calendar, share, invite, ...). Internal numeric ids must never appear in logs.
Example:
slog.ErrorContext(ctx, "eventbus.Append failed",
slog.Any("err", err),
logutil.LogEntity("workspace", ws.PublicID),
logutil.LogEntity("task", task.PublicID),
)
func LogEntityPID ¶
LogEntityPID is the dbtype.PublicID twin of LogEntity for callers that already hold the project's PublicID wrapper (typically code that has just round-tripped through sqlc).
func LogNumber ¶
LogNumber returns a slog.Attr for a numeric value that is not an entity identifier — a count, a byte size, a duration in milliseconds, an HTTP status code.
It exists because slog.Int / slog.Int64 / slog.Uint64 are forbidden in service code. A callee-name-only lint rule cannot tell slog.Int64("row_count", n) from slog.Int64("task_id", id), so the raw constructors are banned outright and the two legitimate shapes get named helpers: LogEntity for identity, LogNumber for everything else.
Passing an id-shaped key redacts the value rather than logging it, so routing an internal id through LogNumber cannot recreate the leak the ban exists to prevent.
func Redact ¶
Redact scans s for any registered secret prefix and replaces every match with "[REDACTED:<prefix>]". The scanner is greedy on the secret token: a match runs until the first non-token character (whitespace, quote, comma, brace, bracket, semicolon, or newline).
A prefix only counts where a word starts (see startsWord). Short prefixes otherwise match inside ordinary English — "sk-" sits inside task-filter, risk-adjusted and disk-usage, "pat_" inside compat_mode, "SG." inside MSG. — and the marker is an assertion that a credential was found at that spot. One planted in prose costs twice: the words it swallows are gone from the stored string, and an operator who reads it investigates a leak that never happened.
The rule belongs here rather than in SecretPrefixes: dropping or lengthening a colliding prefix narrows what the scanner catches, while the boundary rule keeps every prefix and only rejects the positions where a secret cannot begin.
func RedactJSONFields ¶
RedactJSONFields walks raw JSON-ish text and replaces the value of any object field whose key matches redactedSensitiveJSONKeys. The scan is a hand-rolled string walk (no regex, no full json.Decode) so it tolerates non-strict JSON such as logs that interleave structured fragments.
The output is also passed through Redact so prefix matches in non-target fields are still scrubbed.
func RegisterPrefix ¶
func RegisterPrefix(p string)
RegisterPrefix adds a literal secret prefix to the redaction scanner. Safe to call from init functions; it is a no-op if the prefix is already registered or shorter than 4 characters (too short to be specific).
Types ¶
type RedactHandler ¶
type RedactHandler struct {
// contains filtered or unexported fields
}
RedactHandler wraps another slog.Handler and scrubs secret-looking values from record attrs before forwarding.
func NewRedactHandler ¶
func NewRedactHandler(inner slog.Handler) *RedactHandler
NewRedactHandler returns a RedactHandler wrapping inner.