🐦 Implementing Twitter OAuth 1.0a and API v2 in Haskell
🎯 The Goal
🔧 The Automation.Platforms.Twitter module was a stub returning dummy values.
🐦 The TypeScript implementation already handled posting, deleting, and embedding tweets via Twitter API v2 with OAuth 1.0a.
🔄 We needed a complete Haskell port that matches the TypeScript behavior while using only boot-compatible libraries.
🔐 OAuth 1.0a from Scratch
🧮 Twitter API v2 requires OAuth 1.0a authentication, which means building a cryptographic signature for every request.
📝 The signature base string is constructed by concatenating the HTTP method, the percent-encoded URL, and all sorted OAuth parameters joined with ampersands.
🔑 The signing key combines the percent-encoded consumer secret and token secret, separated by an ampersand.
🔏 We sign the base string with HMAC-SHA1 using the crypton library, then base64-encode the result.
📋 The Authorization header lists all OAuth parameters in sorted order, each key and value individually percent-encoded per RFC 5849.
🧱 Percent Encoding
🚫 OAuth percent encoding is stricter than typical URL encoding.
✅ Only unreserved characters pass through unchanged: letters, digits, hyphen, period, underscore, and tilde.
🔢 Every other byte is encoded as a percent sign followed by two uppercase hex digits.
🌐 The implementation works at the byte level, encoding the text to UTF-8 first, then processing each byte individually.
📡 Posting Tweets
📤 The postTweet function sends a POST to the tweets endpoint with a JSON body containing the tweet text.
🆔 A UUID v4 idempotency key is generated once and sent as an X-Idempotency-Key header to prevent duplicate posts on retries.
🔁 The request is wrapped in the existing withRetry infrastructure, which retries on transient HTTP codes like 429, 502, 503, and 504.
🔄 The OAuth header is regenerated on each retry attempt with a fresh timestamp and nonce for correctness.
📦 The response is parsed using our custom Automation.Json module, extracting the tweet ID and text from the nested data object.
🗑️ Deleting Tweets
🧹 The deleteTweet function sends a DELETE request to the tweets endpoint with the tweet ID appended to the URL.
🔐 It uses the same OAuth signing flow but without a request body or idempotency key.
✅ Non-2xx status codes are surfaced as Left values in the Either result.
🖼️ Embed HTML
🌐 The fetchOEmbed function calls the publish.twitter.com oEmbed API with a dark theme and script inclusion enabled.
🔗 The tweet URL is percent-encoded as a query parameter value.
📄 The JSON response is parsed to extract the html field.
🏠 When oEmbed fails, generateLocalEmbed produces a fallback blockquote with the twitter-tweet class, including the tweet text, author attribution, and the Twitter widgets script tag.
🔀 The getEmbedHtml function tries oEmbed first and falls back to local generation, matching the TypeScript behavior exactly.
🏗️ Design Decisions
📦 All functions take an HTTP Manager parameter instead of creating new managers, following the established codebase convention.
🧩 We reuse the existing Automation.Json module for JSON encoding and decoding rather than depending on aeson.
🔁 We leverage Automation.Retry for exponential backoff retry logic with transient error detection.
🛡️ Every IO operation that can fail returns Either Text, giving callers explicit control over error handling.
🎲 UUID generation uses System.Random to produce version 4 UUIDs with proper version and variant bits set.
📊 Summary of Changes
🔧 One file changed with 251 insertions and 32 deletions.
📦 No new dependencies added; the implementation uses crypton, memory, base64-bytestring, random, http-client, and http-types, all already in the cabal file.
✅ All 181 existing tests continue to pass.
🏗️ The module compiles cleanly with GHC 9.14.1 and zero warnings under strict Wall settings.
📚 Book Recommendations
🔗 Similar
- 📖 Real World Haskell by Bryan O Sullivan, Don Stewart, and John Goerzen
- 📖 OAuth 2 in Action by Justin Richer and Antonio Sanso
🔀 Contrasting
- 📖 Designing Data-Intensive Applications by Martin Kleppmann
- 📖 Release It by Michael Nygard
🎨 Creatively Related
- 📖 Cryptography Engineering by Niels Ferguson, Bruce Schneier, and Tadayoshi Kohno
- 📖 Thinking with Types by Sandy Maguire