Activity-Relay Directory 1.3.1

Activity-Relay Directory 1.3.1

Status: stable release draft.

Version information

• Git tag: v1.3.1
• Application version: 1.3.1
• Debian package version: 1.3.1-2
• SQLite schema: 14
• V2 public API: /v2/relays schema 6
• Lifecycle protocols: [1,2,3] when v3 is configured
• Accepted release-candidate source: b6bb1a7828f3a0b01742482bb74651fd53b9a808
• Accepted release-candidate baseline: 1.3.1-rc2
• Previous stable release: v1.3.0

Stable 1.3.1 promotes the accepted 1.3.1-rc2 behavior without runtime
changes. It combines the reachability diagnostics, actor-failure retries and
heartbeat liveness from 1.3.1-rc1 with the public wording from 1.3.1-rc2.

The Debian revision is -2 because an earlier, unreleased 1.3.1-1
candidate package was built and installed for testing before the RC series.
That candidate was never published as a release. Revision -2 keeps the
normal Debian upgrade order above both that candidate and 1.3.1~rc2-1.

What changed since 1.3.0

Reachability diagnostics

The Directory distinguishes DNS resolution, connection, TLS, redirect, HTTP
response, malformed ActivityPub Actor, and ActivityPub Inbox OPTIONS
outcomes instead of reporting every problem as an undifferentiated outage.

When an Actor returns HTTP 404 or 410, or DNS lookup indicates that the name
may no longer exist, the Directory can mark it possibly removed. This is
an interpretation of one observation, not evidence sufficient to delete
the relay. Transient failures such as timeouts and HTTP 5xx responses are not
presented as confirmed decommissioning.

/v2/relays schema 6 adds optional bounded diagnostic objects beneath
Actor reachability and Inbox state, and next_eligible_at, the earliest
eligible time for a background recheck. A diagnostic includes a stage, code,
optional HTTP status, and cautious assessment; it does not contain DNS
addresses, raw exceptions, response bodies, or private discovery provenance.

Ordinary DNS and connection outages are kept separate from prohibited
destination-policy failures, so --add-dead-relays can retain an unreachable
candidate when the normal import policy permits it.

Retries and heartbeat liveness

After a healthy Actor becomes unreachable, the next eligible checks are 1 hour
after the first failure, 2 hours after the second, 4 hours after the third,
and then 6 hours for later failures. A successful Actor check resets the
streak and restores the ordinary six-hour cadence. Relays without positive
online evidence for seven days keep the weekly retry policy. The published
next eligible time is not a promise that a check has already been scheduled
or run.

A current authenticated heartbeat is now independent positive evidence of
relay liveness. A relay with a healthy heartbeat but a failed Actor check is
listed with Other Known Relays (API tier 2), not as offline, and its
Actor failure remains visible. Summary counts and download lists use the same
definitions.

Public website wording

• The existing opt-in authenticated lifecycle protocol is called the
  ARD White Pages Protocol on the public page. No wire format or API names
  change.
• The four groups are ARD White Pages Protocol Relays, Other Known
  Relays, Offline or Unreachable Relays, and Graveyard. Numeric API
  tier values 1–4 are unchanged.
• Heartbeat badges show Healthy, Stale, or No heartbeat received;
  the API keeps its five heartbeat state codes.
• Checks are labelled ActivityPub Actor and ActivityPub Inbox with
  plain-language DNS, connection, HTTPS/TLS, redirect, Actor and Inbox
  messages. TLS failures are shown as TLS error.
• The Inbox check shows its recorded time and notes that message delivery was
  not tested. HTTP 405/501 means the server does not support that check, not
  that ActivityPub delivery is unavailable.

Behavior and compatibility

• SQLite migrations 13 and 14 are the only additions over 1.3.0. Migrations
  1–12 are unchanged.
• Diagnostics do not change authenticated participation timestamps,
  moderation, enrollment, pruning, or hard retention decisions.
• Failed Actor checks retain the previous successful Actor timestamp and
  previously observed Inbox evidence.
• Inbox probing remains a non-mutating OPTIONS request.
• /v1/relays and lifecycle Protocols 1/2/3 remain compatible with 1.3.0.
  The V2 public API schema advances from 5 to 6.
• Activity-Relay ban/block-list coordination is not part of this release.

Detailed field definitions and cautions are in
docs/REACHABILITY-DIAGNOSTICS.md and
docs/PUBLIC-LISTING.md.

Installation and upgrade

The Debian package version is 1.3.1-2. It upgrades normally from 1.3.0-1,
1.3.1~rc1-1, 1.3.1~rc2-1, and the unreleased 1.3.1-1 candidate. An
upgrade preserves existing Directory data and operator-owned configuration.
Package maintainer scripts do not restart an operator-activated service; some
host tools (such as needrestart) may restart it separately. After reviewing
the package and configuration, restart the service deliberately to load the
new binary.

Back up and restore-test the SQLite database before starting 1.3.1 against
it. Starting from 1.3.0 applies schema 13 and schema 14 before the HTTP
listener opens; hosts already on 1.3.1-rc1 or rc2 are already at schema 14 and
no migration runs. In-place database downgrade is unsupported: rollback to
1.3.0 after migration requires the matching pre-upgrade database backup and
the 1.3.0 binary.

Fresh installations keep the established conservative defaults: the service
is not enabled or started, binds to loopback, and leaves lifecycle, public
listing, automatic pruning, retention and administrator email disabled.

Official Debian, standalone binary, CycloneDX SBOM, build metadata, Docker
image archive, and SHA256SUMS assets are published on the Forgejo and GitHub
release pages for v1.3.1.