alan/activity-relay-directory
1
0
Fork 0
Code Issues Pull requests 1 Projects Releases 5 Wiki Activity Actions
5 releases 5 tags
  • v1.2.0 978a90d98e

    v1.2.0
    All checks were successful
    Build / Container (push) Successful in 34s
    Details
    Test / Go 1.26.0 (push) Successful in 3m15s
    Details
    Test / Go 1.26.5 (push) Successful in 3m16s
    Details
    Test / Go 1.27rc2 (forward) (push) Successful in 3m20s
    Details
    Debian Package / Debian package validation (push) Successful in 4m48s
    Details
    Stable

    alan released this 2026-10-03 16:41:34 +00:00 | 25 commits to master since this release

    Signed by alan
    SSH key fingerprint: SHA256:yvtkLe2vkdG0Y1CCxra56JR6gjOJFURf52LUTVpWqPw

    Activity-Relay Directory 1.2.0

    Activity-Relay Directory 1.2 expands relay discovery, long-term availability tracking, and the public-facing Directory while preserving the authenticated V1 lifecycle protocol and the frozen /v1/relays compatibility API.

    Highlights

    • More resilient relay discovery and bulk imports
    • Retention and automatic retry of unavailable relay candidates
    • ActivityStreams Group relay actor support
    • Four public operational relay tiers
    • 30-day transition to the Graveyard tier
    • Aggregate online, offline, and pending-verification counts on the public-facing Directory page
    • Local tier-scoped exports and public plain-text relay downloads
    • Automatic recovery of previously unavailable relays
    • Debian upgrade handling that reloads systemd definitions without automatically restarting an active Directory

    Relay discovery

    Discovery imports now accept:

    • bare hostnames;
    • non-default HTTPS ports;
    • base URLs;
    • /actor URLs; and
    • /inbox URLs.

    A relay must still pass canonical actor validation before becoming verified public Directory state.

    ActivityStreams Group actors are now accepted in addition to the previously supported relay actor forms.

    Imports distinguish between:

    • newly discovered relays;
    • relays already known through discovery or lifecycle state;
    • duplicate lines in the same input; and
    • unavailable or incompatible candidates.

    Existing relay identities are not duplicated merely because they appear in another import.

    Retained unavailable candidates

    discovery import --add-dead-relays can retain unavailable or incompatible candidates privately for future retry.

    Retry timing is:

    • 6 hours
    • 12 hours
    • 24 hours
    • 3 days
    • weekly thereafter

    A retained candidate remains private until a later actor check successfully validates and promotes it. Candidate identities, failure details, source labels, and other discovery provenance are not published.

    Public relay tiers

    Verified relays are grouped into four operational tiers:

    1. Tier 1 — Heartbeat + Online
      The relay has a current Directory heartbeat and is currently reachable.

    2. Tier 2 — Online, no current heartbeat
      The relay is currently reachable but does not have a current Directory heartbeat.

    3. Tier 3 — Offline / Unreachable
      The relay is currently unreachable but has been seen online within the last 30 days.

    4. Tier 4 — Graveyard
      The relay has not been seen online for at least 30 days.

    Relays are ordered alphabetically within each tier. Heartbeat frequency, check recency, popularity, and traffic do not affect placement.

    Graveyard relays are not deleted. They continue periodic recovery checks and automatically return to Tier 1 or Tier 2 if they recover.

    The public-facing Directory page also summarizes the number of verified relays known, currently online, currently offline, and additional candidates pending verification.

    Exports and downloads

    Operators can export relay lists locally:

    activity-relay-directory admin export --scope active --format hosts
activity-relay-directory admin export --scope unavailable --format hosts
activity-relay-directory admin export --scope all --format actors

    When public listing is enabled, host lists are also available at:

    /downloads/active.txt
/downloads/unavailable.txt
/downloads/all.txt

    Host exports preserve non-default HTTPS ports and can be fed back into a later discovery import.

    Private provenance and unresolved candidate identities are never included in exports or public downloads.

    Compatibility

    Activity-Relay Directory 1.2 uses:

    Database schema:        9
/v1/status schema:      3
/v1/relays schema:      1
/v2/relays schema:      3
v2 cursor format:       2
Lifecycle protocol:     1
Minimum Go version:     1.26.0
Debian package version: 1.2.0-1

    /v1/relays remains frozen for 1.0 compatibility.

    Migrations 0001 through 0008 remain byte-identical to the v1.1.0 release. 0009_discovery_candidates.sql is the only new migration in 1.2.

    Existing schema-8 databases upgrade in place to schema 9.

    In-place database downgrade is not supported. Back up the SQLite database before upgrading and restore the matching older backup if returning to an older binary.

    Debian upgrades

    Package upgrades preserve the current service enablement state and do not stop or restart an operator-activated Directory.

    Package configuration automatically reloads systemd unit definitions. After reviewing the upgraded package and configuration, restart the service manually when you are ready to load the new binary:

    sudo systemctl restart activity-relay-directory

    Normal package removal preserves the Directory database and service account. Explicit package purge remains the destructive boundary.

    Safe defaults

    Fresh installations remain deliberately inactive until configured.

    The following remain disabled by default:

    • authenticated lifecycle endpoints;
    • public listing;
    • background reachability maintenance;
    • automatic soft pruning;
    • positive hard-retention policy; and
    • administrator email notifications.

    The public Directory remains read-only. Moderation records, operator reasons, discovery provenance, signatures, nonces, private probe errors, client addresses, database paths, and other administrative information remain private.

    Release acceptance

    The accepted RC2 source passed the 1.2 source acceptance suite covering:

    • schema and migration identity;
    • discovery compatibility;
    • retained-candidate retry and promotion;
    • tiering and 30-day Graveyard behavior;
    • exports and public downloads; and
    • V1/V2 public API compatibility.

    Canonical artifact acceptance additionally verified:

    • exact artifact checksums;
    • Debian RC1 → RC2 upgrade without automatic service restart;
    • automatic systemd daemon reload;
    • manual restart into the upgraded binary;
    • live schema-9 operation;
    • public aggregate relay counts;
    • Docker fresh-volume startup;
    • Docker health/readiness; and
    • Docker named-volume persistence across container recreation.

    Release identity

    Tag:        v1.2.0
Commit:     978a90d98ed4c96928a3970594acb5cecb9cf896
Debian:     1.2.0-1
Schema:     9
    Downloads