Agent Guidelines for Drinkup#

Commands#

• Test: mix test (all), mix test test/path/to/file_test.exs (single file), mix test test/path/to/file_test.exs:42 (single test at line)
• Format: mix format (auto-formats all code)
• Lint: mix credo (static analysis), mix credo --strict (strict mode)
• Compile: mix compile
• Docs: mix docs
• Type Check: mix dialyzer (if configured)

Code Style#

• Imports: Use alias for modules (e.g., alias Drinkup.Firehose.{Event, Options}), require for macros (e.g., require Logger)
• Formatting: Elixir 1.18+, auto-formatted via .formatter.exs with import_deps: [:typedstruct]
• Naming: snake_case for functions/variables, PascalCase for modules, :lowercase_atoms for atoms, @behaviour (not @behavior)
• Types: Use @type and @spec for all functions; use TypedStruct for structs with enforce: true for required fields
• Moduledocs: Public modules need @moduledoc, public functions need @doc with examples
• Error Handling: Return {:ok, result} or {:error, reason} tuples; use with for chaining operations; log errors with Logger.error("#{Exception.format(:error, e, __STACKTRACE__)}")
• Pattern Matching: Prefer pattern matching in function heads over conditionals; use guard clauses when appropriate
• OTP: Use child_spec/1 for custom supervisor specs; :gen_statem for state machines; Task.Supervisor for concurrent tasks; Registry for named lookups
• Tests: Use ExUnit with use ExUnit.Case; use doctest Module for documentation examples
• Dependencies: Core deps include gun (WebSocket), car (CAR format), cbor (encoding), TypedStruct (typed structs), Credo (linting)

Project Structure#

Each namespace (Drinkup.Firehose, Drinkup.Jetstream, Drinkup.Tap) follows a common architecture:

• Core Modules:

  • Consumer - Behaviour/macro for handling events; use Namespace with handle_event/1 implementation
  • Event - Typed event structs specific to the protocol
  • Socket - :gen_statem WebSocket connection manager
  • Options (or top-level utility module) - Configuration and runtime utilities

• Consumer Pattern: use Namespace, opts... with handle_event/1 callback; consumer module becomes a supervisor

Namespace-Specific Details#

• Firehose (Drinkup.Firehose.*): Full AT Protocol firehose

  • Events: Commit, Sync, Identity, Account, Info
  • Additional: RecordConsumer macro for filtered commit records with handle_create/1, handle_update/1, handle_delete/1 callbacks
  • Pattern: use Drinkup.Firehose.RecordConsumer, collections: [~r/app\.bsky\.graph\..+/, "app.bsky.feed.post"]

• Jetstream (Drinkup.Jetstream.*): Simplified JSON event stream

  • Events: Commit, Identity, Account
  • Config: :wanted_collections, :wanted_dids, :compress (zstd)
  • Utility: Drinkup.Jetstream.update_options/2 for dynamic filtering
  • Semantics: Fire-and-forget (no acks)

• Tap (Drinkup.Tap.*): HTTP API + WebSocket indexer/backfill service

  • Events: Record, Identity
  • Config: :host, :admin_password, :disable_acks
  • Utility: Drinkup.Tap HTTP API functions (add_repos/2, remove_repos/2, get_repo_info/2)
  • Semantics: Ack/nack - return :ok/{:ok, _}/nil to ack, {:error, _} to nack (Tap retries)

Important Notes#

• Update CHANGELOG.md when adding features, changes, or fixes under ## [Unreleased] with appropriate sections (Added, Changed, Fixed, Deprecated, Removed, Security)
• WebSocket States: Socket uses :disconnected → :connecting_http → :connecting_ws → :connected flow
• Sequence Tracking: Use Event.valid_seq?/2 to validate sequence numbers from firehose