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 Backpressure() int64
- 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 Sync()
- 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 Backpressure ¶ added in v1.0.180
func Backpressure() int64
Backpressure reports how many request-log entries had to wait for room in the persistence queue. Non-zero means the JSONL sink is not keeping up with the request rate and proxy latency is once again coupled to disk latency — the signal to move the request log to a faster volume. This is a saturation gauge, not a loss counter: steady-state saturation loses nothing (callers wait). Entries that genuinely never reach the file — a failed write, or a saturated queue caught by shutdown — are counted by WriteErrors() instead.
func Close ¶
func Close() error
Close releases the persistent file handle (best-effort; shutdown hook). Safe when persistence was never initialised. It drains the persistence queue first, so entries still in flight at shutdown reach the file rather than being discarded with the goroutine.
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 Sync ¶ added in v1.0.180
func Sync()
Sync blocks until every entry enqueued before the call has been written. It is the deterministic alternative to sleeping: shutdown uses Close (which drains), and tests that assert on file contents call this. Cheap no-op when persistence is not running.
ONE deadline covers BOTH phases — handing the request to the drain goroutine and waiting for it to finish flushing. Timing only the handshake would leave the wait on `done` unbounded, so a sink that wedges inside bw.Flush (a hung NFS mount, a device that stops completing writes) would hang the caller forever. ReadPersistent calls Sync, so that caller is an admin API request: a stalled log volume must degrade the read, never block it indefinitely.
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