Libraries

libs/ holds 25 internal Rust crates that the top-level services share. Most are uninteresting on their own but become load-bearing once you have to change them. This page is the catalog; each grouped page covers a thematic cluster.

Crate index

Crate	Path	Role
utils	libs/utils/	Generic helpers: ids, time, async building blocks, JWT, signal handling, retry. The bigger of the catch-alls.
metrics	libs/metrics/	Prometheus client + macros. The only Prometheus surface used in workspace code.
tracing-utils	libs/tracing-utils/	JSON tracing formatter + OTel exporter setup.
http-utils	libs/http-utils/	Small axum/hyper helpers (request id, error mapping).
pageserver_api	libs/pageserver_api/	Public types shared between pageserver, clients, scrubber, and storage controller.
safekeeper_api	libs/safekeeper_api/	Public types for the safekeeper.
compute_api	libs/compute_api/	The compute spec model.
pq_proto	libs/pq_proto/	Postgres libpq wire protocol parser/serializer.
postgres_backend	libs/postgres_backend/	Server-side libpq abstraction (used by pageserver and safekeeper).
postgres_connection	libs/postgres_connection/	Client-side libpq helpers.
postgres_ffi	libs/postgres_ffi/	Per-PG-version C struct definitions, WAL record layouts, magic numbers.
postgres_ffi_types	libs/postgres_ffi_types/	Smaller type-only counterpart.
postgres_versioninfo	libs/postgres_versioninfo/	Per-PG-version constants.
postgres_initdb	libs/postgres_initdb/	Helpers for bootstrapping a Postgres data directory programmatically.
walproposer	libs/walproposer/	Rust-callable static lib of the C walproposer. Used for safekeeper sim tests.
wal_decoder	libs/wal_decoder/	Decodes raw WAL records into per-page (key, value) tuples.
remote_storage	libs/remote_storage/	S3 + Azure + GCS + LocalFs object-store abstraction.
consumption_metrics	libs/consumption_metrics/	Billing/telemetry types and emitter.
tenant_size_model	libs/tenant_size_model/	Synthetic-size accounting (see docs/synthetic-size.md).
vm_monitor	libs/vm_monitor/	VM-level autoscaling helper running inside compute.
desim	libs/desim/	Deterministic simulator used by safekeeper tests.
posthog_client_lite	libs/posthog_client_lite/	Tiny PostHog client for product analytics.
neon-shmem	libs/neon-shmem/	Shared-memory primitives.
proxy/ (sub-tree)	libs/proxy/	5 proxy-specific crates (postgres-protocol2, tokio-postgres2, postgres-types2, json, subzero_core stub).

Reading order if you're new

1. libs/utils/ — used by everything. Read its lib.rs and skim id.rs.
2. libs/pageserver_api/ — the contract between the pageserver and everything else (compute, scrubber, controller).
3. libs/postgres_ffi/ — the source of truth for what Postgres struct lives where, per supported version.
4. libs/remote_storage/ — used by pageserver, safekeeper, scrubber, and endpoint_storage. Understanding it is required for any cross-cloud work.

Three crates worth a closer look

libs/utils

Houses the project's swiss-army-knife code:

• id.rs — TenantId, TimelineId, ShardIdentity, etc. (16-byte UUID-shaped IDs).
• lsn.rs — the Lsn type, with parsing for the 0/16B5A50 print format.
• auth.rs — JWT signing and verification used by every service.
• task_mgr.rs — graceful shutdown / cancellation token registry.
• signals.rs — SIGINT/SIGTERM handling.
• simple_rcu.rs — a simple RCU primitive used in hot read paths.
• bin_ser.rs — binary serialization helpers.
• failpoint_support.rs — wiring for the fail crate.

Anything you'd want to share between unrelated services tends to land here.

libs/postgres_ffi

The single most "version-aware" crate. Each supported Postgres major version has its own submodule (v14/, v15/, v16/, v17/) with constants and struct layouts for that version. The crate also contains:

• wal_craft/ — synthetic WAL stream generator used in tests to exercise specific record types.
• xlog_utils.rs — WAL segment naming, parsing, and validation.
• Bindings for Postgres's internal data types (RelFileNode, BlockNumber, Pg_class, etc.).

When upstream Postgres changes a struct between minor versions, postgres_ffi is where the shim is added.

libs/remote_storage

The RemoteStorage trait, plus four concrete implementations:

• S3Bucket — backed by aws-sdk-s3. Production.
• AzureBlobStorage — backed by the (forked) azure_storage_blobs crate.
• GcsBucket — recent (2026 Q1), the most actively edited file in this crate.
• LocalFs — a literal directory on disk; used in tests.

The trait surface is small: upload, download, delete, list, plus a few specialized methods (multipart uploads, conditional uploads). A common pattern in calling code is to let the storage backend choose itself from a TOML config block — see pageserver/src/config.rs.

See also

• Patterns and conventions for how these libraries are used.
• The individual crate Cargo.toml files for the version-pinning of dependencies.

For deeper coverage of each thematic cluster, see the rest of this section.