Mastodon API - reference social.
  • Ada 90.1%
  • Python 6.4%
  • JavaScript 1.6%
  • C 1.1%
  • CSS 0.5%
  • Other 0.3%
Find a file
2026-11-22 17:28:26 +01:00
alire Stabbypossum 1.0.0+ka-bar 2026-10-20 16:07:21 +02:00
corpus Stabbypossum 1.0.0+ka-bar 2026-10-20 16:07:21 +02:00
doc doc/timeline-index.md: the design of one append-only index file per timeline, owned by the local worker, with a clean marker, Bloom filters and a recent window in memory; guardian PASS, owner's four decisions pending, nothing built 2026-11-22 00:45:45 +01:00
docs Stabbypossum 1.0.0+ka-bar 2026-10-20 16:07:21 +02:00
etc No audience is collected from random servers any more: a post goes to the author's followers, to the accounts the author follows when it is to the public, to the groups it is sent to and to the actors it mentions or answers, and to nobody else; several on one server still share its one shared inbox. The shared inbox of every actor fetched was written in basedir/inbox and every public post was sent to all of them; that list, Inbox_Add, Inbox_Add_By_Actor, Inbox_List and the disable_inbox_collection setting are gone (a server.json that still has it loads as before), and so is the broadcast handling that existed only for those copies: one try, the broadcast-declined line and its series on the stats page, no receipt, nothing held against the instance. A copy queued by an earlier release with "broadcast" still decodes and is delivered as any other. A followers-only or direct post keeps its addressing; a followed group gets a post only when it is sent to it. The folder of collected inboxes is removed once by the queue loop at its first round, with the count of files at INFO, and again an hour later if that failed (ERR); a new basedir no longer has one, the nightly purge no longer walks it, and /api/v1/instance/peers, which listed its hosts, lists none. 2026-11-20 10:29:37 +01:00
scripts Stabbypossum 1.0.0+ka-bar 2026-10-20 16:07:21 +02:00
smoketest The Stats page's heap-in-use row is the newest memory sample the stats flusher took, where every page load called mallinfo2, which walks glibc's free chunks under each arena's lock and could hold up allocations everywhere; a test run sets STABBYPOSSUM_FRESH_HEAP=1 so the smoke's leak rounds still read the heap at the moment they ask; the selftest finds the row unknown without a sample and the newest sample's value with two 2026-11-21 13:07:38 +01:00
spark SPARK: tmp and the eight lanes are memory states in the replay rule; a publish line puts a new message in tmp's queue and nowhere else; enter and gone lines are read by what they say, so those an earlier release wrote about tmp's and the lanes' folders still replay; the start-up's two cases, queued and a file in a folder, are two predicates and a message is in one queue, one folder or nowhere; V2_Lane_Full sends a control refused a place at its lane's door to that lane's room, and an output overflows at most once; a logical identity can be in flight. gnatprove: every check of both units proved 2026-11-20 01:31:21 +01:00
src Stabbypossum 1.4.31+kaiken: the Stats page shows disk counts the stats flusher takes every five minutes, where every load walked the whole spool tree, the accounts and the instance folders on the NAS (about 31,000 entries, 5 to 9 seconds a load, and the page reloads every minute), so a browser gave up and the connection was reset. Count_Disk walks them at start and after each memory sample and sets a protected snapshot with no I/O inside; the page copies it and says how old the counts are. The memory-state tables stay live. tests/shared_objects.allow names the atomic Listings that replaced Listing_Counter, and the new Disk_Counts. 2026-11-22 17:28:26 +01:00
static Stabbypossum 1.4.25+dirk: an instance that does not answer at all for the threshold, three days by default, gets the new built-in flag Missing Host on the instance's table, written as the admin would with origin protocol-check and kept until somebody removes it, where it went into a register of dead instances: nothing is sent to it or asked of it while the row stands, its receipts say failed, and since the flag is no penalty what it sends comes in and no follow is ended, so removing the row gives everything back; a host with a row of any kind keeps it; the register's dead folder becomes rows at the first start and goes, with the weekly probe, the raising by a signed activity, the Dead instances card and its endpoint; the Stats page counts missing hosts from the rows 2026-11-13 19:36:48 +01:00
tests Stabbypossum 1.4.31+kaiken: the Stats page shows disk counts the stats flusher takes every five minutes, where every load walked the whole spool tree, the accounts and the instance folders on the NAS (about 31,000 entries, 5 to 9 seconds a load, and the page reloads every minute), so a browser gave up and the connection was reset. Count_Disk walks them at start and after each memory sample and sets a protected snapshot with no I/O inside; the page copies it and says how old the counts are. The memory-state tables stay live. tests/shared_objects.allow names the atomic Listings that replaced Listing_Counter, and the new Disk_Counts. 2026-11-22 17:28:26 +01:00
tools Stabbypossum 1.4.31+nessmuk: ingress, validation, ready and local are queues in memory with a journal, where each was a folder every pass of its thread listed on the NAS and every step of it went through the filesystem, so one slow listing of a ready folder of 6,500 files held the whole spool; each state's one worker waits on its bounded queue (Ada.Containers.Bounded_Synchronized_Queues behind Stabbypossum_Spool_Queues, a place taken in a state before anything is written into it and given back once the message has left), and every move into, inside or out of them is one queue move and one JSON line of spool/journal, handed to one writer task that writes what was handed during its last write with one write and one fsync; a move from a folder waits until its enter line is durable, removes its source file, then queues the message; a move to a folder writes a staging file, waits until its gone line is durable, renames the staging file into the folder; so a stop at any instant leaves one answer, which the start-up settles before any thread runs: the source file of a durable enter goes, the staging file of a durable gone is renamed in, a staging file no gone names goes; the start-up folds each message's lines through Step, proved in SPARK to apply only a line V2_Transition_Allowed allows and to leave a message in one state and its lane, writes the live messages as one segment and removes the old ones, and the writer removes a segment once no line in it or before it is still a record; the controls an earlier release left in those folders are taken in by each state's own worker, 64 at a time between turns of work; what comes from outside is still written into tmp before it is answered, so no HTTP task waits on the journal; each worker writes its own atomic gauges and a watchdog says at ERROR which state stopped for a minute with work waiting and what it was doing; the inbox's admission count reads the gauges instead of listing folders; the test hooks read one atomic flag before entering their protected objects; tools/shared_objects.pl lists every package-level object and the build fails on one not in tests/shared_objects.allow with why it may be shared; the selftest runs the real writer and moves, a legacy drain, and a stop at each instruction of each crossing followed by two starts; the smoke starts the server with a journal fsync, a lane's listing, a rename into a lane and a timeline write hung in turn and measures every other state moving 2026-11-19 21:47:29 +01:00
.dockerignore Stabbypossum 1.0.0+ka-bar 2026-10-20 16:07:21 +02:00
.drone.yml Stabbypossum: the image is compiled once, where Dockerfile.amd64 compiled it, ran the unit tests, and compiled it again static; the unit tests move to a stage of their own, --target unittests, built with the development profile and run by the developer before a push; Drone builds the image only and no longer runs the SPARK image, which the developer runs on what changed; a build argument JOBS limits the compilers at once, every core when empty, as Drone's node has 2026-11-19 21:47:29 +01:00
.gitignore Stabbypossum 1.0.0+ka-bar 2026-10-20 16:07:21 +02:00
alire.toml Stabbypossum 1.4.31+nessmuk: ingress, validation, ready and local are queues in memory with a journal, where each was a folder every pass of its thread listed on the NAS and every step of it went through the filesystem, so one slow listing of a ready folder of 6,500 files held the whole spool; each state's one worker waits on its bounded queue (Ada.Containers.Bounded_Synchronized_Queues behind Stabbypossum_Spool_Queues, a place taken in a state before anything is written into it and given back once the message has left), and every move into, inside or out of them is one queue move and one JSON line of spool/journal, handed to one writer task that writes what was handed during its last write with one write and one fsync; a move from a folder waits until its enter line is durable, removes its source file, then queues the message; a move to a folder writes a staging file, waits until its gone line is durable, renames the staging file into the folder; so a stop at any instant leaves one answer, which the start-up settles before any thread runs: the source file of a durable enter goes, the staging file of a durable gone is renamed in, a staging file no gone names goes; the start-up folds each message's lines through Step, proved in SPARK to apply only a line V2_Transition_Allowed allows and to leave a message in one state and its lane, writes the live messages as one segment and removes the old ones, and the writer removes a segment once no line in it or before it is still a record; the controls an earlier release left in those folders are taken in by each state's own worker, 64 at a time between turns of work; what comes from outside is still written into tmp before it is answered, so no HTTP task waits on the journal; each worker writes its own atomic gauges and a watchdog says at ERROR which state stopped for a minute with work waiting and what it was doing; the inbox's admission count reads the gauges instead of listing folders; the test hooks read one atomic flag before entering their protected objects; tools/shared_objects.pl lists every package-level object and the build fails on one not in tests/shared_objects.allow with why it may be shared; the selftest runs the real writer and moves, a legacy drain, and a stop at each instruction of each crossing followed by two starts; the smoke starts the server with a journal fsync, a lane's listing, a rename into a lane and a timeline write hung in turn and measures every other state moving 2026-11-19 21:47:29 +01:00
application_tests.gpr The purge's object scan lists each timeline once, not once per object: for every object older than seven days, Object_MD5_Referenced read a whole Maildir listing of the federated timeline and of Home, Notifications, Groups and Authored of every user, 22 minutes of CPU per purge on the instance and a whole listing alive all along. Collect_Object_References now reads each listing once at the start of the scan and keeps the MD5 of every live copy's object, 16 bytes each in a sorted vector; each object is then looked up in it. The answer is the one the timelines gave: a live copy keeps its object, a copy taken out or none does not, an identity too long for a lookup, a timeline not ready or not listed whole, an account not opened or a user folder not enumerated keep everything (logged once per timeline at WARN, where it was once per object); the canonical object probe, the webfinger answers and the legacy caches are asked as before. The new selftest builds two users and a federated timeline with live copies, a copy taken out, unused objects, a webfinger answer, an object without id and an unreadable one: both questions give the same keep or delete for every object, the collection reads nine listings (federated and four per user) and the lookups none, the purge deletes exactly the aged objects the old question calls unused, and an unreadable account keeps every object both ways. 2026-11-22 01:10:00 +01:00
DOCKER.md The docs give the Docker Hub image 2026-10-20 19:23:23 +02:00
Dockerfile.amd64 Stabbypossum: the image is compiled once, where Dockerfile.amd64 compiled it, ran the unit tests, and compiled it again static; the unit tests move to a stage of their own, --target unittests, built with the development profile and run by the developer before a push; Drone builds the image only and no longer runs the SPARK image, which the developer runs on what changed; a build argument JOBS limits the compilers at once, every core when empty, as Drone's node has 2026-11-19 21:47:29 +01:00
Dockerfile.arm64 Every outbound request has a deadline: 20 s when its caller names none, under 1 KB in 10 s it is dropped, DNS gets 2 s and one try, mail and ntfy are bounded, and a timeout is not asked again unsigned 2026-10-27 19:40:06 +01:00
Dockerfile.builder.amd64 Stabbypossum 1.0.0+ka-bar 2026-10-20 16:07:21 +02:00
Dockerfile.builder.arm64 Stabbypossum 1.0.0+ka-bar 2026-10-20 16:07:21 +02:00
Dockerfile.builder.spark Stabbypossum 1.0.0+ka-bar 2026-10-20 16:07:21 +02:00
Dockerfile.spark Stabbypossum 1.0.0+ka-bar 2026-10-20 16:07:21 +02:00
fs_atomic_replace_proof.gpr Stabbypossum 1.0.0+ka-bar 2026-10-20 16:07:21 +02:00
fs_atomic_replace_tests.gpr Stabbypossum 1.0.0+ka-bar 2026-10-20 16:07:21 +02:00
fs_nfs_rename_tests.gpr Stabbypossum 1.0.0+ka-bar 2026-10-20 16:07:21 +02:00
fs_probe_tests.gpr Stabbypossum 1.0.0+ka-bar 2026-10-20 16:07:21 +02:00
groups_tests.gpr Stabbypossum 1.0.0+ka-bar 2026-10-20 16:07:21 +02:00
INSTALL.md The docs give the Docker Hub image 2026-10-20 19:23:23 +02:00
journal.md Stabbypossum 1.0.0+ka-bar 2026-10-20 16:07:21 +02:00
LICENSE.md Stabbypossum 1.0.0+ka-bar 2026-10-20 16:07:21 +02:00
logs_loweel_stabbypossum_246_1_2.log Stabbypossum 1.0.0+ka-bar 2026-10-20 16:07:21 +02:00
README.md Stabbypossum 1.4.31+kaiken: the Stats page shows disk counts the stats flusher takes every five minutes, where every load walked the whole spool tree, the accounts and the instance folders on the NAS (about 31,000 entries, 5 to 9 seconds a load, and the page reloads every minute), so a browser gave up and the connection was reset. Count_Disk walks them at start and after each memory sample and sets a protected snapshot with no I/O inside; the page copies it and says how old the counts are. The memory-state tables stay live. tests/shared_objects.allow names the atomic Listings that replaced Listing_Counter, and the new Disk_Counts. 2026-11-22 17:28:26 +01:00
spark_helpers.gpr Stabbypossum 1.4.31+puukko: the queue of each spool state kept in memory is a FIFO proved in SPARK, where it was Ada.Containers.Bounded_Synchronized_Queues: a ring whose Put keeps every element and adds one at the end, whose Take gives the first and moves the rest up, never past its capacity, proved by gnatprove through an instance on Integer with a capacity of seven; a protected object around it only excludes and waits; the selftest fills validation to its limit and finds it empties in the order it was filled, each once; nothing the spool does changes 2026-11-19 22:42:57 +01:00
spool_v2_policy_tests.gpr Stabbypossum 1.0.0+ka-bar 2026-10-20 16:07:21 +02:00
stabbypossum.gpr Stabbypossum 1.0.0+ka-bar 2026-10-20 16:07:21 +02:00
TODO-resume.md Stabbypossum 1.0.0+ka-bar 2026-10-20 16:07:21 +02:00

Stabbypossum

Stabbypossum is a usable ActivityPub server written in Ada.

At this stage it starts as a source-guided port of snac2, especially for the visible interfaces and filesystem behavior. The long-term goal is not to pretend that Ada is C, but to carry the same small-server idea into a codebase with stronger type safety, better modularity, and a maintenance model that fits exposed Internet software.

The short version is: Daddy is Snac.

Why

snac2 is fascinating because it proves that a single-person project can still implement a practical ActivityPub server without turning into a large platform. ActivityPub federation is difficult, and the protocol often feels much more complicated than it needs to be. snac2 approaches that problem with discipline: plain storage, small moving parts, and a bias toward direct, understandable behavior.

Stabbypossum exists because that approach deserves an Ada implementation.

This is not a claim that snac2 has specific security problems. It is a different engineering bet: C can be used extremely well by expert programmers, but Internet-facing C services also live close to classes of memory and data handling bugs that Ada is designed to make harder. Stabbypossum tries to keep the practical minimalism of snac2 while gaining Ada type and data safety.

Also, it is fun.

Goals

  • Keep the visible behavior close to snac2 while the port is young.
  • Use snac2 as the design map: simple filesystem storage, simple processes, clear HTTP behavior, and as little machinery as possible.
  • Avoid a database. The filesystem is the storage model.
  • Keep configuration transparent and inspectable.
  • Make the project suitable for small Docker deployments.
  • Fit homelab-scale servers, including very small machines and NFS-backed storage.
  • Stay aligned with snac2 development where that makes sense.
  • Eventually let Stabbypossum grow its own features once the port has legs.

Current Status

Current version: Stabbypossum/1.4.31+kaiken.

Stabbypossum runs live instances and is the software behind the author's own.

The project currently has working ActivityPub federation for the implemented S2S flows, filesystem storage, Web UI work, WebFinger and actor output, login/admin scaffolding, and the subset of the Mastodon client API implemented by snac2. Comparative smoke tests exercise Stabbypossum and a real snac2 server side by side.

If this sounds interesting, follow the project and expect the feature list and release notes to become useful as the implementation matures.

Implemented So Far

The implemented list is intentionally conservative. It should only describe what exists in the code today.

  • Ada project built with Alire.
  • Filesystem-based server and user storage.
  • User creation with local key material.
  • WebFinger responses for local users.
  • ActivityPub actor endpoint with local profile data.
  • Web login and a Semantic UI client for home, federated and hashtag timelines, notifications, conversations, profiles, people, follow requests, bookmarks, pinned posts, followed hashtags, lists, and search.
  • The Web UI uses locally vendored Atkinson Hyperlegible Mono by default.
  • Web composer and status controls for replies, media, content warnings, polls, scheduling, visibility, language, likes, reposts, bookmarks, pins, edits, deletion, and emoji reactions.
  • Remote media attachments and remote custom emoji caching for inbound S2S posts.
  • Settings UI for Mastodon-compatible profile fields and advanced local settings, including CSV contact-list import and asynchronous resettling.
  • Inbox and shared-inbox request handling.
  • Input, shared input, output, and local user queues.
  • Signed ActivityPub delivery for S2S output, to the author's followers, the accounts the author follows (for a public post), the groups a post is sent to and the actors it mentions or answers, and nobody else; one copy per server through its shared inbox.
  • HTTP signature checking for queued inbound S2S messages.
  • Basic S2S handling for Follow, Accept Follow, Undo Follow, Create, Update, Delete, Like, Announce, EmojiReact, Ping/Pong, and Move behavior.
  • Filesystem indexes for timeline objects, replies, likes, announces, emoji reactions, public objects, blocked instances, failed instances, and public hashtags.
  • snac-style handling for content rejection filters, blocked hashtags, followed hashtag distribution, dropped DMs from unknown actors, and blocked/muted actors.
  • The Mastodon client API subset implemented by snac2, including its OAuth authorization flow.
  • A Debian 12 multi-stage container image and a single-replica Docker Swarm deployment with separate data and configuration mounts.
  • Smoke tests that exercise the implemented HTTP and storage behavior and keep selected responses aligned with snac2.

What It Is Not Yet

  • It is not a complete ActivityPub server.
  • It is not yet a conservative production recommendation for unattended public instances.
  • It does not implement Mastodon's entire API, only the subset implemented by snac2.

Development installation is documented in INSTALL.md. Container and Docker Swarm deployment is documented in DOCKER.md. Container images use the loweel/stabbypossum Docker Hub repository as their publication target.

Design Shape

Stabbypossum is meant to stay small.

The intended deployment model is a tiny ActivityPub instance for one person or a few users, especially in a homelab. The concrete target environment is Docker on small machines, such as ODROID-class nodes, with storage that can live on NFS. Ada plus Docker should make the executable and runtime environment highly reproducible, while filesystem storage keeps data visible and easy to reason about.

Relationship With snac2

snac2 by grunfink is the reference, inspiration, and credit source for this project. Stabbypossum initially follows it as a port for the externally visible interfaces and for many internal storage and queue decisions.

The goal is not to redesign the product while porting it. The goal is to understand what snac2 does, reproduce the behavior in Ada, and then only add new direction once there is a solid foundation.

One intentional divergence is the browser admin login flow. snac2 exposes the admin page through an HTTP Basic authentication challenge; Stabbypossum redirects unauthenticated /user/admin browser requests to its OAuth-style Web UI login page and then uses the instance_ui session cookie for the admin shell and Web UI actions. The ActivityPub and Mastodon-compatible API compatibility tests should not assume snac2-style Basic-auth behavior for Stabbypossum's Web UI.

License

Stabbypossum is intended to be licensed under the European Union Public Licence, using the current version or later: EUPL-1.2-or-later.

Acknowledgements

  • snac2 and grunfink, for the design path and the practical approach this project follows.
  • Braille Institute, for the Atkinson Hyperlegible font family used by the Web UI.
  • OpenAI Codex, for refreshing my memory about Ada. The last time I seriously programmed in Ada, it was still called Ada 95 and ran on SGI machines.
  • OpenMoji, Twemoji, and Noto Emoji, for the bundled custom-emoji packs (see static/stabbypossum/emoji-packs/README.md for per-pack licenses and attribution).

Contact

This is a personal project, and feedback is welcome through the channels below.

  • Email: uriel.fanelli@keinpfusch.net
  • Matrix: @uriel:chat.keinpfusch.net