Documentation
¶
Overview ¶
Package reqlog is the request-log engine: a bounded in-memory ring (the newest MaxRing entries), an optional persistent JSONL layer with rotation and a count-once-log-first write-error contract, a bounded newest-first read over the persistent file with a short-TTL shared-parse cache, and the status→level mapping. Extracted from package main's store.go per ADR-0002 (store.go decomposition Phase C — the slice that closes the program).
package main keeps the surfaces: AuthLogFields and its applyTo (welded to the frozen AuthOutcome contract), the recordRequest*/persistLogEntry fan-out (stats globals + syslog forwarding + this layer), and the API handlers. One inversion point: the queryable-history hook (SetHistory) — main wires a closure performing the same lock-free atomic load the inline code did, so runtime enable/disable of the history store stays race-free on the hot path.
Index ¶
- Constants
- func Add(e Entry)
- func Close() error
- func ExpireCacheForTest()
- func FilePath() string
- func Init(path string, maxMB int) error
- func LevelForStatus(status string) string
- func PersistActive() bool
- func PinCacheForTest()
- func ResetForTest()
- func SetFilePathForTest(path string) (restore func())
- func SetHistory(fn func(Entry))
- func SetWriterForTest(w io.Writer) (restore func())
- func SkippedLines() int64
- func SwapPersistenceForTest() (restore func())
- func SwapRingForTest() (restore func())
- func WriteErrors() int64
- type Entry
Constants ¶
const MaxPersistentReturn = 20000
MaxPersistentReturn caps the newest-N entries returned from the persistent JSONL request log so admin queries remain bounded regardless of the on-disk rotation size. Roughly one day of traffic at ~100 req/s.
const MaxRing = 5000
MaxRing bounds the in-memory ring buffer.
Variables ¶
This section is empty.
Functions ¶
func Add ¶
func Add(e Entry)
Add appends an entry to the in-memory ring and, when configured, to the persistent JSONL file and the queryable-history hook.
func Close ¶
func Close() error
Close releases the persistent file handle (best-effort; shutdown hook). Safe when persistence was never initialised.
func ExpireCacheForTest ¶
func ExpireCacheForTest()
ExpireCacheForTest zeroes the read-cache expiry so the next ReadPersistent re-parses the file.
func FilePath ¶
func FilePath() string
FilePath reports the configured persistent JSONL path ("" = disabled).
func Init ¶
Init opens a rotating JSONL file for persistent request logging. Each Entry is appended as a single JSON line. The file rotates at maxMB. If path is empty this is a no-op (backwards-compatible).
func LevelForStatus ¶
LevelForStatus maps a request status to the log level driving the admin UI's tab grouping (INFO = allowed, WARN = blocked & threats, ERROR = auth failures and anything unexpected).
func PersistActive ¶
func PersistActive() bool
PersistActive reports whether a persistent file handle is wired (test support for the startup/shutdown-hook coverage).
func PinCacheForTest ¶
func PinCacheForTest()
PinCacheForTest pushes the read-cache expiry far into the future so a "served from cache" assertion cannot flake on a slow host.
func ResetForTest ¶
func ResetForTest()
ResetForTest unwires the persistent layer so tests can safely re-init without leaking file handles or paths across tests. Safe to call whether or not persistence was initialised. (No restore — mirrors the pre-extraction resetRequestLogState helper's exact semantics.)
func SetFilePathForTest ¶
func SetFilePathForTest(path string) (restore func())
SetFilePathForTest points persistent reads at path without opening a writer, returning a restore func.
func SetHistory ¶
func SetHistory(fn func(Entry))
SetHistory installs the queryable-history hook called after every Add.
func SetWriterForTest ¶
SetWriterForTest points JSONL persistence at w (closer and path stay as they are), returning a restore func. Used to inject failing writers.
func SkippedLines ¶
func SkippedLines() int64
SkippedLines reports the number of corrupt JSONL lines skipped on read.
func SwapPersistenceForTest ¶
func SwapPersistenceForTest() (restore func())
SwapPersistenceForTest snapshots and clears the writer/closer/path trio, returning a restore func. The restore closes whatever handle the test left wired (so a re-init inside the test cannot leak) before reinstating the snapshot.
func SwapRingForTest ¶
func SwapRingForTest() (restore func())
SwapRingForTest swaps the in-memory ring for an empty one, returning a restore func, so Add side-effects don't leak across tests.
func WriteErrors ¶
func WriteErrors() int64
WriteErrors reports the number of failed JSONL marshals/writes in Add.
Types ¶
type Entry ¶
Entry is the request-log record. The history store (internal/logstore) owns the wire/SIEM field contract; this engine rings, persists, and reads the same type so there is exactly one schema.
func ReadPersistent ¶
ReadPersistent streams the persistent JSONL request log file and returns the newest-first slice of parsed entries, capped at MaxPersistentReturn so memory stays bounded regardless of file size. Callers should apply their own filter + pagination loop on top — the same loop they use on the in-memory ring buffer — so there is a single filter code path to maintain.
Returns (nil, nil) when persistence is disabled (no file configured) or when the file has not yet been created. Only the active (non-rotated) log file is consulted; the rotated ".1" archive is intentionally skipped to keep each query bounded to one rotation window.
Source Files