src/workerd/util/

OVERVIEW

Shared utility library: data structures, SQLite wrapper, feature gating, logging, thread-local scopes. No workerd-specific API dependencies — consumed across api/, io/, server/.

KEY UTILITIES

File	What	Notes
state-machine.h	Type-safe kj::OneOf wrapper with transition locking	Prevents UAF in callbacks; 7 consumers in api/streams/
sqlite.h/c++	Full SQLite wrapper with custom VFS over kj::Directory	Regulator controls allowed SQL; Statement for prepared queries
sqlite-kv.h	KV abstraction on SQLite	Used by Durable Object storage
autogate.h/c++	Runtime feature gates	AutogateKey enum; isEnabled() check; 8 active gates
weak-refs.h	WeakRef<T> / AtomicWeakRef<T>	Non-owning refs; tryAddStrongRef() or runIfAlive(fn) pattern
ring-buffer.h	Amortized O(1) deque	Replaces std::list in streams
small-set.h	kj::OneOf-based set	O(1) for 0–2 items, fallback to kj::HashSet
batch-queue.h	Double-buffered cross-thread queue	Producer/consumer with mutex swap
checked-queue.h	Safe std::list wrapper	pop() returns Maybe instead of UB on empty
strong-bool.h	WD_STRONG_BOOL(Name) macro	Type-safe boolean; prevents implicit conversions
sentry.h	LOG_EXCEPTION, LOG_ONCE, LOG_PERIODICALLY	DEBUG_FATAL_RELEASE_LOG = debug assert + release warning
thread-scopes.h	Thread-local scope flags	Self-described "horrible hacks"; AllowV8BackgroundThreadsScope, MultiTenantProcess
abortable.h	newAbortableInputStream/OutputStream	Wraps KJ streams with disconnect capability
stream-utils.h	NeuterableInputStream, newNullInputStream	Disconnectable I/O; null/identity stream factories
mimetype.h	MIME type parser/serializer	MimeType::extract() from content-type header
wait-list.h	Cross-request event subscription	Shared fulfiller list for signaling waiters

Guidelines

• No bool arguments: use WD_STRONG_BOOL for type safety and readability
• Use kj::Maybe for optional values: avoid null pointers and sentinel values
• Prefer composition over inheritance: utilities should be standalone and reusable without complex class hierarchies
• Use StateMachine for state management: original pattern has been to use kj::OneOf directly, and that's still acceptable for simple cases, but StateMachine provides additional safety guarantees and should be preferred for more complex state management

ANTI-PATTERNS

• StateMachine forceTransitionTo(): bypasses terminal state protection — use only for error recovery
• StateMachine underlying(): bypasses ALL safety (transition lock, terminal states) — last resort only
• StateMachine + KJ_SWITCH_ONEOF: does NOT acquire transition lock — UAF risk; use whenState<T>(fn) instead
• StateMachine deferTransitionTo(): first-wins semantics; second call silently ignored
• SQLite: SQLITE_MISUSE always throws; virtual tables disallowed (except FTS5); ATTACH/DETACH forbidden; callbacks must not write
• ThreadScopes: thread-local state crossing module boundaries — acknowledged hack, do not proliferate
• RingBuffer: moves on grow invalidating references; iterators invalidated on push/pop; intentionally not thread-safe.