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
  • v1.1.0 b446891e94

    Activity-Relay Directory 1.1.0
    All checks were successful
    Build / Container (push) Successful in 2m12s
    Details
    Debian Package / Debian package validation (push) Successful in 2m43s
    Details
    Test / Go 1.27rc2 (forward) (push) Successful in 3m13s
    Details
    Test / Go 1.26.5 (push) Successful in 3m30s
    Details
    Test / Go 1.26.0 (push) Successful in 3m31s
    Details
    Stable

    alan released this 2026-09-17 03:47:44 +00:00 | 46 commits to master since this release

    Signed by alan
    SSH key fingerprint: SHA256:yvtkLe2vkdG0Y1CCxra56JR6gjOJFURf52LUTVpWqPw

    Activity-Relay Directory 1.1.0

    Status: stable release.

    Version information

    • Git tag: v1.1.0
    • Application version: 1.1.0
    • Debian package version: 1.1.0-1
    • Accepted release candidate: v1.1.0-rc2
    • Previous stable release: v1.0.0

    What's new in 1.1

    Activity-Relay Directory 1.1 adds operator-controlled relay discovery,
    independent reachability checks, a richer V2 public API, and an improved
    human-facing directory.

    The accepted 1.1.0-rc2 behavior is being promoted to stable without runtime
    behavior changes. Stable 1.1.0 will be built and published as its own release;
    the published RC2 files and container image remain unchanged.

    Relay discovery and reachability

    Operators can add relays for discovery without treating them as registered
    lifecycle participants. Directory can separately check whether a relay actor is
    reachable and can record non-mutating inbox diagnostics.

    Heartbeat and reachability remain separate. A relay can therefore have an old
    or missing lifecycle heartbeat while still being reachable, or have a recent
    heartbeat while a later reachability check fails.

    Discovered-only relays must have a recent successful actor check to remain
    eligible for the public directory. Administrative suspension takes precedence
    over both registered and discovered relay eligibility.

    Human-facing pages

    The human-facing directory uses compact, responsive relay rows with clearer
    heartbeat and reachability information.

    Larger directories provide Previous and Next navigation so visitors can move
    through the listing in either direction. The human-facing pages use the same
    public relay information as the V2 public API while keeping detailed technical
    diagnostics out of the main listing.

    V1 Protocol and compatibility

    The authenticated V1 Protocol remains unchanged. Existing Activity-Relay
    clients continue to use the same registration, heartbeat, and unregister
    behavior.

    The /v1/relays public API also remains compatible with Activity-Relay
    Directory 1.0. Its wire format and established behavior are unchanged.

    Compatibility versions remain:

    • database schema: 8
    • /v1/status schema: 3
    • /v1/relays schema: 1
    • lifecycle protocol: version 1
    • Go module floor: 1.26.0

    V2 public API

    GET /v2/relays provides the richer 1.1 public relay listing. It is disabled by
    default along with the human-facing directory.

    The V2 public API can show heartbeat state, actor reachability, validated inbox
    information, and positive RFC 9421 evidence while keeping those observations
    separate. Discovered-only relays are not given artificial registration or
    heartbeat timestamps.

    This is version 2 of the public relay API; it does not introduce a V2 lifecycle
    protocol.

    Discovery provenance, operator notes and reasons, private probe errors, audit
    events, database identifiers, request signatures, client addresses, resolver
    details, and internal participation flags are not published.

    Package upgrades and removal

    Normal package upgrades and package removal preserve the Directory database and
    the dedicated activity-relay-directory service account. This allows the
    package to be upgraded or reinstalled without discarding retained Directory
    state.

    Explicit package purge is the destructive boundary: it removes the package's
    state directory and dedicated service account.

    /etc/activity-relay-directory/config.yml remains operator-owned. It is not a
    package conffile and is not deleted by the custom package-maintenance scripts.

    Upgrade notes

    Schema 8 adds the 1.1 discovery and reachability data. Existing installations
    upgrade in place.

    Before upgrading an existing installation, take and verify a standalone SQLite
    backup. In-place database downgrade is not supported; to return to an older
    release, restore the database backup made for that older version.

    Safe defaults

    A fresh installation remains inactive until an operator enables the features
    they want:

    • lifecycle routes are disabled;
    • enrollment is closed;
    • the public directory is disabled;
    • background reachability checks are disabled;
    • automatic soft pruning is disabled;
    • inactive-record retention is 0 (indefinite); and
    • administrator email is disabled.

    Enabling the public directory does not automatically enable lifecycle
    registration, reachability checks, pruning, retention, or any public
    state-changing route.

    Downloads
  • v1.1.0-rc2 8aafe65153

    Activity-Relay Directory 1.1.0-rc2
    All checks were successful
    Build / Container (push) Successful in 1m41s
    Details
    Test / Go 1.27rc2 (forward) (push) Successful in 3m22s
    Details
    Test / Go 1.26.5 (push) Successful in 3m23s
    Details
    Test / Go 1.26.0 (push) Successful in 3m31s
    Details
    Debian Package / Debian package validation (push) Successful in 5m6s
    Details
    Pre-release

    alan released this 2026-09-17 01:21:05 +00:00 | 47 commits to master since this release

    Signed by alan
    SSH key fingerprint: SHA256:yvtkLe2vkdG0Y1CCxra56JR6gjOJFURf52LUTVpWqPw

    Activity-Relay Directory 1.1.0-rc2

    Status: release-candidate source draft. Canonical artifacts, tag, publication,
    deployment, and feature activation remain separate gates.

    1.1.0-rc1 was prepared as a source candidate but was not tagged or published.
    This RC2 draft supersedes that unpublished candidate after the human-directory
    and Debian lifecycle corrections merged to master.

    Version identity

    • Git tag: v1.1.0-rc2
    • Application version: 1.1.0-rc2
    • Debian package version: 1.1.0~rc2-1
    • Stable baseline: v1.0.0
    • RC2 pre-freeze baseline merge: b181f599d0d48720dcaacd385f68a48b46c4de80
    • Prior 1.1.0-rc1 tag/publication: none

    Candidate scope

    Activity-Relay Directory 1.1 continues to add operator-controlled discovery and
    independent relay reachability without changing the authenticated version 1
    lifecycle or reinterpreting heartbeat recency. Schema version 8 records
    discovery state, actor/inbox observations, and positive RFC 9421 evidence while
    preserving private provenance and audit boundaries.

    RC2 carries the RC1 1.1 feature set and adds the following post-RC1 corrections:

    • scale the human directory into compact responsive relay rows with clearer
      heartbeat and reachability presentation while intentionally leaving detailed
      inbox/RFC 9421 evidence in the JSON projection;
    • add signed previous/next navigation to the human directory using the existing
      bounded v2 cursor format, while keeping /v2/relays itself forward-only;
    • make Debian package removal non-destructive for retained SQLite state and the
      dedicated service account, with explicit package purge as the destructive
      boundary;
    • keep operator-owned /etc/activity-relay-directory/config.yml outside the
      package conffile set and outside maintainer-script deletion; and
    • validate built maintainer scripts and package ownership boundaries under a
      Debian Trixie / debhelper >= 13.25 release-build contract.

    These changes do not introduce a new database migration, lifecycle protocol
    version, or public JSON schema version beyond the RC1 1.1 candidate.

    Compatibility and schemas

    • Database schema: 8.
    • /v1/status schema: 3.
    • /v1/relays schema: 1, frozen for 1.0 compatibility.
    • /v2/relays schema: 2.
    • Lifecycle protocol: version 1.
    • Go module floor: 1.26.0; release toolchain: 1.26.5.

    Migrations 0001 through 0007 remain byte-identical to the v1.0.0 release;
    0008_discovery_reachability.sql remains the only 1.1 migration. Existing
    retained lifecycle/audit state upgrades in place to schema 8. In-place database
    downgrade is unsupported: take and verify a standalone SQLite backup before
    upgrade, and restore the matching older backup when downgrading.

    Human directory and public contract

    /v1/relays retains the 1.0 wire and semantic contract. The v2 projection keeps
    lifecycle heartbeat, actor reachability, inbox diagnostics, and RFC 9421
    evidence independent. Discovered-only relays never receive fabricated
    registration or heartbeat timestamps. Administrative suspension overrides both
    registration and discovery eligibility.

    The human / view remains a presentation over the same bounded v2 projection.
    It now supports signed reverse traversal with before in addition to normal
    forward cursor navigation. Reverse traversal does not extend the original
    five-minute walk lifetime. /v2/relays remains forward-only and rejects the
    human-only reverse parameter.

    Discovery source/provenance, operator and reason values, private probe errors,
    audit events, database identifiers, request signatures, client addresses,
    resolver details, and internal participation flags remain non-public.

    Debian lifecycle contract

    Ordinary package removal and upgrade preserve
    /var/lib/activity-relay-directory and the dedicated
    activity-relay-directory system account so the package can be reinstalled or
    upgraded without discarding retained directory state.

    Package purge is explicitly destructive: it removes the state directory and the
    dedicated system user/group. The optional
    /etc/activity-relay-directory/config.yml is operator-owned, is not a package
    conffile, and is not deleted by the custom maintainer scripts. The package-created
    parent directory is removed only when otherwise empty. Purge under DPKG_ROOT
    is rejected rather than attempting destructive account/state cleanup against an
    alternate root.

    The release builder inspects the generated .deb, requires generated postinst,
    prerm, and postrm scripts, checks their shell syntax, proves the custom
    destructive operations occur only behind the purge guard, verifies the exact
    package conffile set, and confirms operator config.yml is absent from the
    payload.

    Default safety posture

    Fresh installations remain deliberately inert until configured. In particular:

    • lifecycle routes remain disabled by default and enrollment remains closed;
    • public directory presentation remains disabled by default;
    • background reachability remains disabled by default;
    • automatic soft pruning remains disabled by default;
    • inactive-record retention remains 0 (indefinite); and
    • administrator email remains disabled.

    Enabling the public listing does not activate lifecycle, reachability, pruning,
    retention, or any public mutation route.

    Source and release-build gates

    The accepted 1.1 source gate continues to cover exact 1.0.0/schema-7 upgrade
    identity, registered and discovered-only participation paths, candidate URL
    convergence, fail-closed resolver/network behavior, inbox method rejection, a
    real RFC 9421 signed lifecycle request persisted through SQLite, independent
    registration/discovery transitions, suspension, pruning races, and schema-8
    inactive retention.

    The RC2 pre-freeze master baseline additionally passed Forgejo container,
    Debian package, and Go test workflows after the human-directory and Debian
    lifecycle corrections were merged. Canonical package construction now runs on
    the shared forgejo-workstation execution profile, requires Debian Trixie,
    installs debhelper from Trixie backports, and fails closed below version
    13.25.

    This source-preparation commit must still pass the normal branch/PR checks before
    it becomes the exact reviewed source identity for a canonical RC2 dispatch.

    Candidate artifact and operator gates

    Forgejo is authoritative. After this candidate-preparation source state is
    reviewed and merged, the manual exact-commit workflow must build one new
    canonical 1.1.0-rc2 artifact set. The Debian package and Docker archive from
    that exact set must then be independently install-tested using separate SQLite
    state and bind ports before tagging or publication.

    Do not relabel RC1 or 1.0.0 artifacts. Tagging, release publication, deployment,
    activation of the default-off 1.1 surfaces, production verification/soak, and
    stable 1.1 promotion remain separate explicit approvals.

    Downloads
  • v1.0.0 69af9c1bce

    Activity-Relay Directory 1.0.0
    All checks were successful
    Build / Container (push) Successful in 1m45s
    Details
    Test / Go 1.26.5 (push) Successful in 4m38s
    Details
    Test / Go 1.26.0 (push) Successful in 4m40s
    Details
    Test / Go 1.27rc2 (forward) (push) Successful in 4m41s
    Details
    Debian Package / Debian package validation (push) Successful in 5m20s
    Details
    Stable

    alan released this 2026-09-03 02:55:03 +00:00 | 66 commits to master since this release

    Signed by alan
    SSH key fingerprint: SHA256:yvtkLe2vkdG0Y1CCxra56JR6gjOJFURf52LUTVpWqPw

    Activity-Relay Directory 1.0.0

    Status: first stable release.

    Version identity

    • Git tag: v1.0.0
    • Application version: 1.0.0
    • Debian package version: 1.0.0-1
    • Accepted release-candidate baseline: 0.1.0-rc4
    • There is no final v0.1.0 tag.

    Stable scope

    Activity-Relay Directory 1.0.0 promotes the accepted RC4 runtime contract to
    stable. The stable-preparation source delta is limited to release/version
    metadata, documentation, and generalizing the exact-commit canonical artifact
    workflow so it can build stable semantic versions. It does not change the Go
    runtime behavior accepted during the RC soak.

    The stable service provides the version 1 authenticated register, heartbeat,
    and unregister lifecycle; bounded health projection; default-off public JSON
    and human listings; local enrollment/moderation/pruning/retention/storage
    administration; durable replay protection; SSRF-resistant actor/key
    resolution; and SQLite-backed audited state.

    Compatibility and schemas

    • Database schema: 7.
    • /v1/status schema: 3.
    • /v1/relays schema: 1.
    • Lifecycle protocol: version 1.
    • Go module floor: 1.26.0; release toolchain: 1.26.5.

    The stable release preserves the RC migration contract. In-place database
    downgrade is not supported. Before upgrading an existing deployment, take and
    verify a standalone SQLite backup. To downgrade, restore the database backup
    that matches the older binary rather than starting an older binary against a
    newer schema.

    Accepted live integration

    The first stable release was accepted against the Activity-Relay 3.0 release
    line using directory.argentwolf.org as a real Directory service. Acceptance
    included:

    • successful schema-3 status consumption by Activity-Relay;
    • registration and public projection of both relay.argentwolf.org and
      relay2.argentwolf.org;
    • natural scheduler-driven heartbeat refresh from both relays after the daily
      interval;
    • healthy public projection throughout the soak;
    • authenticated removal of relay2 with durable local suppression;
    • confirmed absence of relay2 from /v1/relays while disabled; and
    • re-enable plus automatic scheduler registration returning relay2 to the
      healthy public listing.

    The Compose lifecycle exercise also established an operator requirement for
    Activity-Relay deployments that bind config.yml as a single file: an atomic
    host-file replacement is not visible to an already-running container using the
    old bind-mounted inode. Activity-Relay operator documentation carries the safe
    container sequence; this is not a Directory protocol or persistence defect.

    Default safety posture

    Fresh installations remain deliberately inert until configured:

    • lifecycle routes are disabled;
    • enrollment is closed;
    • the public listing and human directory are disabled;
    • automatic soft pruning is disabled;
    • inactive-record retention is 0 (indefinite); and
    • administrator email is disabled.

    Package installation remains separate from service activation. The Debian
    package does not enable or start the service automatically, and package removal
    or purge does not delete SQLite state.

    Release artifacts

    Forgejo is authoritative. The canonical exact-commit workflow builds one
    checksummed artifact set containing the Debian package, standalone binary,
    CycloneDX SBOM, build metadata, and Docker-loadable linux/amd64 image archive.
    The exact accepted bytes are promoted to the release surface; do not rebuild or
    rename RC4 artifacts as 1.0.0.

    Downloads
  • v0.1.0-rc1 b3b8c62c33

    Activity Relay Directory 0.1.0-rc1
    All checks were successful
    Build / Container (push) Successful in 1m24s
    Details
    Test / Go 1.27rc2 (forward) (push) Successful in 2m27s
    Details
    Test / Go 1.26.0 (push) Successful in 2m51s
    Details
    Test / Go 1.26.5 (push) Successful in 2m52s
    Details
    Debian Package / Debian package validation (push) Successful in 4m10s
    Details
    Pre-release

    alan released this 2026-08-12 02:30:04 +00:00 | 77 commits to master since this release

    Signed by alan
    SSH key fingerprint: SHA256:yvtkLe2vkdG0Y1CCxra56JR6gjOJFURf52LUTVpWqPw

    Activity Relay Directory 0.1.0-rc1

    This is the first release candidate toward Activity Relay Directory 1.0.0.

    Canonical release artifacts were built once from the reviewed signed source
    commit b3b8c62c33feab7e361fe754a56dd9c2f13dd8dd (tree 3b52940bf63962eefd819df4fde9144799c155cc) and promoted without rebuild.

    The exact Debian package and Docker archive were independently install-tested
    on a clean Ubuntu 26.04 LTS amd64 VM. Fresh Debian installation remained
    disabled/inactive until explicit operator activation; both Debian and container
    paths passed health/readiness/status checks and the default-off lifecycle and
    public-listing contract using separate writable SQLite state.

    Included release files:

    • activity-relay-directory_0.1.0-rc1-1_amd64.deb
    • activity-relay-directory_0.1.0-rc1_amd64.cdx.json
    • activity-relay-directory_0.1.0-rc1_linux_amd64
    • BUILD-METADATA.txt
    • activity-relay-directory_0.1.0-rc1_linux_amd64.docker.tar
    • SHA256SUMS

    Verify the five checksummed canonical assets with:

    sha256sum -c SHA256SUMS

    Application version: 0.1.0-rc1
    Debian version: 0.1.0~rc1-1

    This is a prerelease candidate, not the 1.0.0 stable release.

    Downloads