arizuko › components › mastd

mastd

What it is

mastd is the Mastodon channel adapter. It opens the user streaming API on a configured Mastodon instance, filters notifications to mentions and DMs, and posts inbound to gated. Outbound goes through the Mastodon REST API. JID prefix is mastodon:; per-account JIDs are mastodon:<account_id>.

Why it exists

Mastodon is the fediverse foothold: one adapter speaks ActivityPub against any Mastodon instance the operator has an account on. Streaming is the only practical way to get low-latency notifications — polling the public API hits rate limits before the bot becomes useful.

How it fits

Mastodon instance
        |  streaming API: /api/v1/streaming/user (SSE)
        v
      mastd     (LISTEN_ADDR=:8080)
        |  POST /v1/messages    (signed by CHANNEL_SECRET)
        v
      gated
        |  POST /v1/send         (callback to mastd)
        v
      mastd     (REST: /api/v1/statuses, /favourite, /reblog, ...)
        |
        v
      Mastodon

Wired verbs (mastd/client.go): send and reply (POST /api/v1/statuses, with in_reply_to_id when set), post (text-only toot), like (/favourite), delete, repost (/reblog), edit (PUT /api/v1/statuses/{id}). forward, quote, dislike are 501-with-hint — Mastodon has no quote primitive (treated as anti-feature on the network) and no downvote.

send_file is not implemented; the adapter returns NoFileSender until the POST /api/v2/media flow lands. send posts publicly today — DM semantics require an acct handle plus Toot.Visibility = "direct", which the current JID format does not carry.

Standalone usage

mastd is a plain Go binary. It needs a reachable gated and an access token from a Mastodon application registered on the target instance.

export ROUTER_URL=http://gated:8080
export CHANNEL_SECRET=$(grep ^CHANNEL_SECRET .env | cut -d= -f2)
export LISTEN_ADDR=:8080
export MASTODON_INSTANCE_URL=https://mastodon.social
export MASTODON_ACCESS_TOKEN=...
./mastd

Mastodon-side setup: Preferences → Development → New application on your instance. Required scopes: read, write, follow. Copy the access token.

GET /health returns 503 when the notification stream is down. Mastodon instances sometimes reset the stream; mastd reconnects automatically — a persistent 503 points at the instance, not the adapter.

Go deeper