mastd

What it is

In plain terms, mastd is the connector that plugs Mastodon into arizuko, so the agent can read mentions and DMs and reply as posts.

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 routd. 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
      routd
        |  POST /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 routd and an access token from a Mastodon application registered on the target instance.

export ROUTER_URL=http://routd: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

components/channels — cross-adapter verb matrix.
mastd/README.md — verb table, known gaps (DM semantics, media on post).