···11-# perlds
11+# perlsky
2233-`perlds` is a Perl 5 implementation of an AT Protocol Personal Data Server.
33+`perlsky` is a Perl 5 implementation of an AT Protocol Personal Data Server.
4455Current direction:
66···13131414Reference differential validation:
15151616-- Run `script/differential-validate` to compare `perlds` against the official published `@atproto/pds` on a focused set of account, repo, moderation, sync, firehose, and `importRepo` snapshot-restore behaviors.
1616+- Run `script/differential-validate` to compare `perlsky` against the official published `@atproto/pds` on a focused set of account, repo, moderation, sync, firehose, and `importRepo` snapshot-restore behaviors.
1717- The differential harness also configures a local relay/crawler mock for both servers and verifies that both emit `com.atproto.sync.requestCrawl` notices with the expected hostname after repo activity, based on the upstream crawler wiring in `packages/pds/src/crawlers.ts`, `context.ts`, and `sequencer.ts`.
1818-- Run `PERLDS_DIFF_ACCOUNT_DID_METHOD=did:plc script/differential-validate` to exercise the same harness in PLC-account mode, including recommended DID credentials, PLC signature requests, PLC handle updates, token-gated PLC signing behavior, and moderation checks after PLC handle changes.
1818+- Run `PERLSKY_DIFF_ACCOUNT_DID_METHOD=did:plc script/differential-validate` to exercise the same harness in PLC-account mode, including recommended DID credentials, PLC signature requests, PLC handle updates, token-gated PLC signing behavior, and moderation checks after PLC handle changes.
1919- The helper installs the reference runtime into `.tools/reference-runtime` with Node 20 via `fnm`.
2020-- Run `PERLDS_RUN_REFERENCE_DIFF=1 prove -lv t/reference-differential.t` to exercise the same harness from the test suite.
2121-- Run `PERLDS_RUN_REFERENCE_DIFF=1 prove -lv t/reference-differential-plc.t` to run the PLC-specific reference comparison from the test suite.
2020+- Run `PERLSKY_RUN_REFERENCE_DIFF=1 prove -lv t/reference-differential.t` to exercise the same harness from the test suite.
2121+- Run `PERLSKY_RUN_REFERENCE_DIFF=1 prove -lv t/reference-differential-plc.t` to run the PLC-specific reference comparison from the test suite.
22222323Metrics and observability:
24242525-- `perlds` now exposes Prometheus-compatible metrics at `/metrics`.
2525+- `perlsky` now exposes Prometheus-compatible metrics at `/metrics`.
2626- Set `metrics_token` to require `Authorization: Bearer <token>` for scrapes.
2727- The main runtime signals cover XRPC request counts/latency, websocket subscriptions and emitted frames, crawler notifications, blob ingress/egress bytes, and key store operation timings.
2828- Detailed operator documentation lives in `docs/METRICS.md`.
···31313232- Configure `hostname` to the public host name you want relays to crawl, for example `pds.example.com`. This should be the host, not the full URL.
3333- Configure `crawlers` as a list of relay or crawler service origins, for example `["https://bsky.network"]`.
3434-- `perlds` will POST `com.atproto.sync.requestCrawl` to each configured crawler after local repo/account/identity activity, while throttling repeat notices with `crawler_notify_interval` (default `1200` seconds).
3434+- `perlsky` will POST `com.atproto.sync.requestCrawl` to each configured crawler after local repo/account/identity activity, while throttling repeat notices with `crawler_notify_interval` (default `1200` seconds).
3535- Local regression coverage for this path lives in `t/crawlers.t`.
36363737Moderation and labels:
···4646Interop fixtures:
47474848- `t/crypto-interop.t` loads the official Bluesky `tools/reference/atproto/interop-test-files/crypto/w3c_didkey_K256.json` vectors so secp256k1 `did:key` encoding stays pinned to the same public fixtures as the upstream stack.
4949-- `t/plc-identity.t` drives `perlds` against the local PLC mock built on the official `@did-plc/lib`, covering account creation, recommended DID credentials, PLC handle updates, token-gated PLC signing, and validated PLC submission semantics.
4949+- `t/plc-identity.t` drives `perlsky` against the local PLC mock built on the official `@did-plc/lib`, covering account creation, recommended DID credentials, PLC handle updates, token-gated PLC signing, and validated PLC submission semantics.
+20-20
docs/METRICS.md
···11# Metrics
2233-`perlds` now exposes Prometheus-style metrics at `/metrics`.
33+`perlsky` now exposes Prometheus-style metrics at `/metrics`.
4455## Security
66···10101111## Main Metrics
12121313-- `perlds_xrpc_requests_total`
1313+- `perlsky_xrpc_requests_total`
1414 Counts HTTP XRPC requests by method, NSID, endpoint type, and status.
1515-- `perlds_xrpc_request_duration_seconds`
1515+- `perlsky_xrpc_request_duration_seconds`
1616 Histogram for HTTP XRPC latency with the same labels.
1717-- `perlds_subscription_connections_total`
1717+- `perlsky_subscription_connections_total`
1818 Counts websocket subscription opens by NSID.
1919-- `perlds_subscription_active`
1919+- `perlsky_subscription_active`
2020 Gauge of active websocket subscriptions by NSID.
2121-- `perlds_subscription_closes_total`
2121+- `perlsky_subscription_closes_total`
2222 Counts websocket closes by NSID and close code.
2323-- `perlds_subscription_frames_total`
2323+- `perlsky_subscription_frames_total`
2424 Counts emitted websocket frames by NSID, frame type, and encoding.
2525-- `perlds_subscription_bytes_total`
2525+- `perlsky_subscription_bytes_total`
2626 Counts emitted websocket bytes by NSID and encoding.
2727-- `perlds_subscription_duration_seconds`
2727+- `perlsky_subscription_duration_seconds`
2828 Histogram of websocket lifetime by NSID.
2929-- `perlds_crawler_requests_total`
2929+- `perlsky_crawler_requests_total`
3030 Counts outbound `com.atproto.sync.requestCrawl` calls by crawler service and result.
3131-- `perlds_crawler_request_duration_seconds`
3131+- `perlsky_crawler_request_duration_seconds`
3232 Histogram of outbound crawler request latency.
3333-- `perlds_blob_ingress_bytes_total`
3333+- `perlsky_blob_ingress_bytes_total`
3434 Counts uploaded blob bytes by MIME type.
3535-- `perlds_blob_egress_bytes_total`
3535+- `perlsky_blob_egress_bytes_total`
3636 Counts downloaded blob bytes by MIME type.
3737-- `perlds_store_operations_total`
3737+- `perlsky_store_operations_total`
3838 Counts instrumented SQLite-backed store operations by operation and status.
3939-- `perlds_store_operation_duration_seconds`
3939+- `perlsky_store_operation_duration_seconds`
4040 Histogram of instrumented store operation duration.
4141-- `perlds_build_info`
4141+- `perlsky_build_info`
4242 Static build/service info gauge.
43434444## Current Store Coverage
···57575858## Suggested Alerts
59596060-- high error rate on `perlds_xrpc_requests_total`
6161-- sustained increase in `perlds_xrpc_request_duration_seconds`
6262-- non-zero `perlds_subscription_active` with no corresponding frame growth
6363-- crawler errors from `perlds_crawler_requests_total{result="error"}`
6060+- high error rate on `perlsky_xrpc_requests_total`
6161+- sustained increase in `perlsky_xrpc_request_duration_seconds`
6262+- non-zero `perlsky_subscription_active` with no corresponding frame growth
6363+- crawler errors from `perlsky_crawler_requests_total{result="error"}`
6464- large ingress with low egress or vice versa on blob byte counters
6565- persistent growth in store latency histograms
6666