🐘 Implementing the Mastodon Platform Module in Haskell
🎯 The Goal
🔧 The Automation.Platforms.Mastodon module was a stub with placeholder functions returning Nothing and False.
🐘 The TypeScript implementation already supported posting, deleting, and embedding Mastodon statuses.
🔄 We needed a complete Haskell implementation following the same patterns established by the Twitter module.
🔑 Bearer Token Authentication
🎟️ Unlike Twitter’s complex OAuth 1.0a signature dance, Mastodon uses straightforward Bearer token authentication.
📨 Every API request includes an Authorization header with the format Bearer followed by the access token.
🧹 This simplicity means no HMAC signing, no nonce generation, and no timestamp-based signature construction.
📮 Posting Statuses
🌐 The postToMastodon function sends a POST request to the instance’s statuses endpoint at api v1 statuses.
📝 The JSON body includes the status text, a visibility field set to public, and a language field set to en.
🔁 For retry safety, each request carries a UUID-based Idempotency-Key header, ensuring duplicate requests from retries do not create duplicate posts.
📦 The response is parsed using the project’s custom JSON module to extract the status id and url fields into a MastodonPostResult record.
⚠️ HTTP errors are thrown as HttpCodeException values, enabling the retry module to recognize transient failures and retry automatically.
🗑️ Deleting Statuses
🎯 The deleteMastodonPost function sends a DELETE request to the status-specific endpoint.
✅ On success it returns Right unit, and on failure it returns Left with an error message.
🔒 The same Bearer token authentication is used for delete operations.
🖼️ Embed HTML Generation
🌐 The fetchMastodonOEmbed function queries the instance’s oEmbed API endpoint, passing the post URL as a query parameter.
📄 The response JSON is parsed to extract the html field, which contains the rich embed markup.
🏠 When oEmbed fails for any reason, the generateLocalMastodonEmbed function provides a fallback.
📐 The fallback generates an iframe pointing to the post’s embed endpoint, styled with max-width 100 percent and no border, at 400 pixels wide.
📜 It also includes a script tag loading the instance’s embed.js file asynchronously, matching the TypeScript reference implementation exactly.
🔀 The getMastodonEmbedHtml function orchestrates this by trying oEmbed first and falling back to the iframe on any error.
🏗️ Following Established Patterns
🐦 The implementation closely mirrors the Twitter module’s structure, using the same error handling pattern with try, Either Text, and HttpCodeException.
🔌 All functions accept a Manager parameter rather than creating a new TLS manager per call, supporting connection pooling.
📦 The project’s custom Automation.Json module is used throughout instead of aeson, keeping the dependency footprint minimal.
🧮 UUID generation for idempotency keys uses the same algorithm as the Twitter module.
🧪 Test Coverage
✅ Twenty unit tests cover all pure functions including URL extraction, username parsing, and embed generation.
🔍 Five property-based tests using QuickCheck verify that URL parsing and embed generation behave correctly across a wide range of inputs.
🏷️ Tests verify specific HTML attributes like mastodon-embed class, iframe src, width, style, allowfullscreen, and the async embed script tag.
📋 The test module follows the same Tasty framework pattern used by the Bluesky and other existing test suites.
📚 Book Recommendations
🟢 Similar
- 📖 Haskell Programming from First Principles by Christopher Allen and Julie Moronuki
- 📖 Real World Haskell by Bryan O’Sullivan, Don Stewart, and John Goerzen
- 📖 Programming in Haskell by Graham Hutton
🔴 Contrasting
- 📖 Programming TypeScript by Boris Cherny
- 📖 Eloquent JavaScript by Marijn Haverbeke
- 📖 The Pragmatic Programmer by David Thomas and Andrew Hunt
🔵 Creatively Related
- 📖 Mastering API Architecture by James Gough, Daniel Bryant, and Matthew Auburn
- 📖 REST API Design Rulebook by Mark Masse
- 📖 Designing Data-Intensive Applications by Martin Kleppmann