code
Clone this repository
https://tangled.org/bretton.dev/coves
git@knot.bretton.dev:bretton.dev/coves
For self-hosted knots, clone URLs may differ based on your setup.
Endpoints implemented:
- GET /xrpc/social.coves.community.get - Retrieve by DID or handle
- GET /xrpc/social.coves.community.list - List with filters
- GET /xrpc/social.coves.community.search - Full-text search
- POST /xrpc/social.coves.community.create - Create community
- POST /xrpc/social.coves.community.subscribe - Subscribe to feed
- POST /xrpc/social.coves.community.unsubscribe - Unsubscribe
Security notes:
- TODO(Communities-OAuth): Authentication currently client-controlled
- MUST integrate OAuth middleware before production
- Authorization enforced at service layer
- Proper error mapping to HTTP status codes
Handles community events from firehose:
- Create/Update/Delete community profiles
- Subscribe/Unsubscribe events
- Uses atomic transaction methods for consistency
Key features:
- Idempotent event handling for replay safety
- Extracts community DID from record (not repo owner)
- Uses SubscribeWithCount for atomic count updates
- Proper error handling with graceful degradation
- Logs all indexed events for observability
Database schema:
- communities table with pg_trgm indexes for fuzzy search
- community_subscriptions with composite index for lookups
- community_memberships with reputation tracking
- community_moderation (V2 prepared)
Repository features:
- Atomic SubscribeWithCount/UnsubscribeWithCount transactions
- Idempotent operations for Jetstream replay safety
- Full-text search with relevance filtering (>0.2 threshold)
- Pagination and filtering support
- Proper error handling with domain error mapping
Performance optimizations:
- Composite index on (user_did, community_did) for subscription lookups
- GIN indexes for trigram similarity search
- GREATEST(0, count - 1) prevents negative counts
- Domain types: Community, Subscription, Membership
- Service layer implements atProto write-forward architecture
- Creates records on PDS (not directly in DB)
- Repository interface for AppView indexing
- Domain errors with proper categorization
- Authorization checks for community updates
Key architectural decisions:
- Communities are instance-scoped (V1)
- Records stored in instance's repo on PDS
- Community DID is metadata, not repo owner
- Service writes to PDS → Firehose → Consumer → AppView DB
- social.coves.community.create - Procedure for creating communities
- social.coves.community.profile - Community profile record schema
- social.coves.community.update - Procedure for updating communities
- Add lexicon validation test data
- Follows atProto lexicon specification for federated records
- Add CommitEvent struct for handling record commits from firehose
- Extends JetstreamEvent to support commit kind
- Required for indexing community records from Jetstream
- Part of Communities feature preparation