# Community Feeds Implementation

**Status:** ✅ Implemented (Alpha)
**PR:** #1 - Community Feed Discovery
**Date:** October 2025

---

## Problem Statement

### What We're Solving

Users need a way to **browse and discover posts** in communities. Before this implementation:

❌ **No way to see what's in a community**
- Users could create posts, but couldn't view them
- No community browsing experience
- No sorting or ranking algorithms
- No pagination for large feeds

❌ **Missing core forum functionality**
- Forums need "Hot", "Top", "New" sorting
- Users expect Reddit-style ranking
- Need to discover trending content
- Must handle thousands of posts per community

### User Stories

1. **As a user**, I want to browse /c/gaming and see the hottest posts
2. **As a user**, I want to see top posts from this week in /c/cooking
3. **As a user**, I want to see newest posts in /c/music
4. **As a moderator**, I want posts ranked by engagement to surface quality content

---

## Solution: Hydrated Community Feeds

### Architecture Decision

We chose **hydrated feeds** over Bluesky's skeleton pattern for Alpha:

```
┌────────────┐
│   Client   │
└─────┬──────┘
      │ GET /xrpc/social.coves.feed.getCommunity?community=gaming&sort=hot
      ▼
┌─────────────────────┐
│   Feed Service      │ ← Validates request, resolves community DID
└─────────┬───────────┘
          ▼
┌─────────────────────┐
│   Feed Repository   │ ← Single SQL query with JOINs
│   (PostgreSQL)      │    Returns fully hydrated posts
└─────────┬───────────┘
          ▼
    [Full PostViews with author, community, stats]
```

**Why hydrated instead of skeleton + hydration?**

| Criterion | Hydrated (Our Choice) | Skeleton Pattern |
|-----------|----------------------|------------------|
| **Requests** | 1 | 2 (skeleton → hydrate) |
| **Latency** | Lower | Higher |
| **Complexity** | Simple | Complex |
| **Flexibility** | Fixed algorithms | Custom feed generators |
| **Right for Alpha?** | ✅ Yes | ❌ Overkill |
| **Future-proof?** | ✅ Can add later | N/A |

**Decision:** Ship fast with hydrated feeds now, add skeleton pattern in Beta when users request custom algorithms.

**Alpha Scope (YAGNI):**
- ✅ Basic community sorting (hot, top, new)
- ✅ Public feeds only (no authentication required)
- ❌ Viewer state (deferred to feed generator phase)
- ❌ Custom feed algorithms (deferred to Beta)

This keeps Alpha simple and focused on core browsing functionality.

---

## Implementation Details

### 1. Sorting Algorithms

#### **Hot (Reddit Algorithm)**

Balances score and recency for discovery:

```sql
ORDER BY (score / POWER(age_hours + 2, 1.5)) DESC
```

**How it works:**
- New posts with low scores can outrank old posts with high scores
- Decay factor (1.5) tuned for forum dynamics
- Posts "age out" naturally over time

**Example:**
- Post A: 100 upvotes, 1 day old → Rank: 10.4
- Post B: 10 upvotes, 1 hour old → Rank: 3.5
- Post C: 50 upvotes, 12 hours old → Rank: 5.1

**Result:** Fresh content surfaces while respecting engagement

#### **Top (Score-Based)**

Pure engagement ranking with timeframe filtering:

```sql
WHERE created_at > NOW() - INTERVAL '1 day'
ORDER BY score DESC
```

**Timeframes:**
- `hour` - Last 60 minutes
- `day` - Last 24 hours (default)
- `week` - Last 7 days
- `month` - Last 30 days
- `year` - Last 365 days
- `all` - All time

#### **New (Chronological)**

Latest first, simple and predictable:

```sql
ORDER BY created_at DESC
```

### 2. Pagination

**Keyset pagination** for stability:

```
Cursor format (base64): "score::created_at::uri"
Delimiter: :: (following Bluesky convention)
```

**Why keyset over offset?**
- ✅ No duplicates when new posts appear
- ✅ No skipped posts when posts are deleted
- ✅ Consistent performance at any page depth
- ✅ Works with all sort orders

**Cursor formats by sort type:**
- `new`: `timestamp::uri` (e.g., `2025-10-20T12:00:00Z::at://...`)
- `top`/`hot`: `score::timestamp::uri` (e.g., `100::2025-10-20T12:00:00Z::at://...`)

**Why `::` delimiter?**
- Doesn't appear in ISO timestamps (which contain single `:`)
- Doesn't appear in AT-URIs
- Bluesky convention for cursor pagination
- Prevents parsing ambiguity

**Example cursor flow:**
```
Page 1: No cursor
  → Returns posts 1-25 + cursor="100::2025-10-20T12:00:00Z::at://..."

Page 2: cursor from page 1
  → Returns posts 26-50 + cursor="85::2025-10-20T11:30:00Z::at://..."

Page 3: cursor from page 2
  → Returns posts 51-75 + cursor (or null if end)
```

### 3. Data Model

#### **FeedViewPost** (Wrapper)

```go
type FeedViewPost struct {
    Post   *PostView   // Full post with all metadata
    Reason *FeedReason // Why in feed (pin, repost) - Beta
    Reply  *ReplyRef   // Reply context - Beta
}
```

#### **PostView** (Hydrated Post)

```go
type PostView struct {
    URI        string         // at://did:plc:abc/social.coves.community.post.record/123
    CID        string         // Content ID
    RKey       string         // Record key (TID)
    Author     *AuthorView    // Author with handle, avatar, reputation
    Community  *CommunityRef  // Community with name, avatar
    Title      *string        // Post title
    Text       *string        // Post content
    TextFacets []interface{}  // Rich text (bold, mentions, links)
    Embed      interface{}    // Union: images/video/external/quote
    CreatedAt  time.Time      // When posted
    IndexedAt  time.Time      // When AppView indexed it
    Stats      *PostStats     // Upvotes, downvotes, score, comments
    // Viewer: Not included in Alpha (deferred to feed generator phase)
}
```

#### **SQL Query** (Single Query Performance)

```sql
SELECT
    p.uri, p.cid, p.rkey,
    p.author_did, u.handle, u.display_name, u.avatar,  -- Author
    p.community_did, c.name, c.avatar,                  -- Community
    p.title, p.content, p.content_facets, p.embed,      -- Content
    p.created_at, p.indexed_at,
    p.upvote_count, p.downvote_count, p.score, p.comment_count
FROM posts p
INNER JOIN users u ON p.author_did = u.did
INNER JOIN communities c ON p.community_did = c.did
WHERE p.community_did = $1
    AND p.deleted_at IS NULL
    AND (cursor_filter)
ORDER BY (hot_rank) DESC
LIMIT 25
```

**Performance:** One query returns everything - no N+1, no second hydration call.

---

## API Specification

### Endpoint

```
GET /xrpc/social.coves.feed.getCommunity
```

### Request Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `community` | string | ✅ Yes | - | Community DID or handle |
| `sort` | string | ❌ No | `"hot"` | Sort order: `hot`, `top`, `new` |
| `timeframe` | string | ❌ No | `"day"` | For `top` sort: `hour`, `day`, `week`, `month`, `year`, `all` |
| `limit` | integer | ❌ No | `15` | Posts per page (max: 50) |
| `cursor` | string | ❌ No | - | Pagination cursor from previous response |

### Response

```json
{
  "feed": [
    {
      "post": {
        "uri": "at://did:plc:gaming123/social.coves.community.post.record/abc",
        "cid": "bafyrei...",
        "author": {
          "did": "did:plc:alice",
          "handle": "alice.bsky.social",
          "displayName": "Alice",
          "avatar": "https://cdn.bsky.app/avatar/..."
        },
        "community": {
          "did": "did:plc:gaming123",
          "name": "gaming",
          "avatar": "https://..."
        },
        "title": "Just finished Elden Ring!",
        "text": "What an incredible journey...",
        "embed": {
          "$type": "social.coves.embed.images#view",
          "images": [
            {"fullsize": "https://...", "alt": "Final boss screenshot"}
          ]
        },
        "createdAt": "2025-10-20T12:00:00Z",
        "indexedAt": "2025-10-20T12:00:05Z",
        "stats": {
          "upvotes": 42,
          "downvotes": 3,
          "score": 39,
          "commentCount": 15
        }
      }
    }
    // ... 24 more posts
  ],
  "cursor": "Mzk6MjAyNS0xMC0yMFQxMjowMDowMFo6YXQ6Ly8uLi4="
}
```

### Example Requests

#### Browse hot posts in /c/gaming
```bash
curl 'http://localhost:8081/xrpc/social.coves.feed.getCommunity?community=gaming&sort=hot&limit=25'
```

#### Top posts this week in /c/cooking
```bash
curl 'http://localhost:8081/xrpc/social.coves.feed.getCommunity?community=did:plc:cooking&sort=top&timeframe=week'
```

#### Page 2 of new posts
```bash
curl 'http://localhost:8081/xrpc/social.coves.feed.getCommunity?community=gaming&sort=new&cursor=Mzk6...'
```

---

## Error Handling

### Error Responses

| Error | Status | When |
|-------|--------|------|
| `CommunityNotFound` | 404 | Community doesn't exist |
| `InvalidRequest` | 400 | Invalid parameters |
| `InvalidCursor` | 400 | Malformed pagination cursor |
| `InternalServerError` | 500 | Database or system error |

### Example Error

```json
{
  "error": "CommunityNotFound",
  "message": "Community not found"
}
```

---

## Code Structure

### Package Organization

```
internal/
├── core/feeds/                    # Business logic
│   ├── interfaces.go              # Service & Repository contracts
│   ├── service.go                 # Validation, community resolution
│   ├── types.go                   # Request/Response models
│   └── errors.go                  # Error types
├── db/postgres/
│   └── feed_repo.go               # SQL queries, sorting algorithms
└── api/
    ├── handlers/feed/
    │   ├── get_community.go       # HTTP handler
    │   └── errors.go              # Error mapping
    └── routes/
        └── feed.go                # Route registration
```

### Service Layer Flow

```
1. HandleGetCommunity (HTTP handler)
   ↓ Parse query params

2. FeedService.GetCommunityFeed
   ↓ Validate request (sort, limit, timeframe)
   ↓ Resolve community identifier (handle → DID)

3. FeedRepository.GetCommunityFeed
   ↓ Build SQL query (ORDER BY based on sort)
   ↓ Apply timeframe filter (for top)
   ↓ Apply cursor pagination
   ↓ Execute single query with JOINs
   ↓ Scan rows into PostView structs
   ↓ Build pagination cursor from last post

4. Return FeedResponse
   ↓ Array of FeedViewPost
   ↓ Cursor for next page (if more results)
```

---

## Testing Strategy

### Unit Tests (Future)

- [ ] Feed service validation logic
- [ ] Cursor encoding/decoding
- [ ] Sort clause generation
- [ ] Timeframe filtering

### Integration Tests (Required)

- [x] Test hot/top/new sorting with real posts
- [x] Test pagination (3 pages, verify no duplicates)
- [x] Test community resolution (handle → DID)
- [x] Test error cases (invalid community, bad cursor)
- [x] Test empty feed (new community)
- [x] Test limit validation (zero, negative, over max)

### Integration Test Results

**All tests passing ✅**

```bash
PASS: TestGetCommunityFeed_Hot (0.02s)
PASS: TestGetCommunityFeed_Top_WithTimeframe (0.02s)
  PASS: Top_posts_from_last_day (0.00s)
  PASS: Top_posts_from_all_time (0.00s)
PASS: TestGetCommunityFeed_New (0.02s)
PASS: TestGetCommunityFeed_Pagination (0.05s)
PASS: TestGetCommunityFeed_InvalidCommunity (0.01s)
PASS: TestGetCommunityFeed_InvalidCursor (0.01s)
  PASS: Invalid_base64 (0.00s)
  PASS: Malicious_SQL (0.00s)
  PASS: Invalid_timestamp (0.00s)
  PASS: Invalid_URI_format (0.00s)
PASS: TestGetCommunityFeed_EmptyFeed (0.01s)
PASS: TestGetCommunityFeed_LimitValidation (0.01s)
  PASS: Reject_limit_over_50 (0.00s)
  PASS: Handle_zero_limit_with_default (0.00s)

Total: 8 test cases, 12 sub-tests
```

**Test Coverage:**
- ✅ Hot algorithm (score decay over time)
- ✅ Top algorithm (timeframe filtering: day, all-time)
- ✅ New algorithm (chronological ordering)
- ✅ Pagination (3 pages, no duplicates, cursor stability)
- ✅ Error handling (invalid community, malformed cursors)
- ✅ Security (cursor injection, SQL injection attempts)
- ✅ Edge cases (empty feeds, zero/negative limits)

**Location:** `tests/integration/feed_test.go`

---

## Performance Considerations

### Database Indexes

Required indexes for optimal performance:

```sql
-- Hot sorting (uses score and created_at)
CREATE INDEX idx_posts_community_hot
ON posts(community_did, score DESC, created_at DESC)
WHERE deleted_at IS NULL;

-- Top sorting (score only)
CREATE INDEX idx_posts_community_top
ON posts(community_did, score DESC, created_at DESC)
WHERE deleted_at IS NULL;

-- New sorting (chronological)
CREATE INDEX idx_posts_community_new
ON posts(community_did, created_at DESC)
WHERE deleted_at IS NULL;
```

### Query Performance

- **Single query** - No N+1 problems
- **JOINs** - users and communities (always small cardinality)
- **Pagination** - Keyset, no OFFSET scans
- **Filtering** - `deleted_at IS NULL` uses partial index

**Expected performance:**
- 25 posts with full metadata: **< 50ms**
- 1000+ posts in community: **Still < 50ms** (keyset pagination)

---

## Future Enhancements (Beta)

### 1. Feed Generators (Skeleton Pattern)

Allow users to create custom algorithms:

```
GET /xrpc/social.coves.feed.getSkeleton?feed=at://alice/feed/best-memes
  → Returns: [uri1, uri2, uri3, ...]

GET /xrpc/social.coves.community.post.get?uris=[...]
  → Returns: [full posts]
```

**Use cases:**
- User-created feeds ("Best of the week")
- Algorithmic feeds ("Rising posts", "Controversial")
- Filtered feeds ("Gaming news only", "No memes")

### 2. Viewer State (Feed Generator Phase)

**Status:** Deferred - Not needed for Alpha's basic community sorting

Include viewer's relationship with posts when implementing feed generators:

```json
"viewer": {
  "vote": "up",
  "voteUri": "at://...",
  "saved": true,
  "savedUri": "at://...",
  "tags": ["read-later", "favorite"]
}
```

**Implementation Plan:**
- Wire up OptionalAuth middleware to feed routes
- Extract viewer DID from auth context
- Query viewer state tables (votes, saves, blocks)
- Include in PostView response

**Requires:**
- Votes table (user_did, post_uri, vote_type)
- Saved posts table
- Blocks table
- Tags table

**Why deferred:** Alpha only needs raw community sorting (hot/new/top). Viewer-specific features like upvote highlighting and saved posts will be implemented when we build the feed generator skeleton.

### 3. Post Type Filtering (Feed Generator Phase)

**Status:** Deferred - Not needed for Alpha's basic community sorting

Filter by embed type when implementing feed generators:

```
GET ...?postTypes=image,video
  → Only image and video posts
```

**Implementation Plan:**
- Check `embed->>'$type'` in SQL WHERE clause
- Map to friendly types (text, image, video, link, quote)
- Support both single (`postType`) and array (`postTypes`) filtering

**Why deferred:** Alpha displays all posts without filtering. Post type filtering will be useful in feed generators for specialized feeds (e.g., "images only").

### 4. Pinned Posts (Feed Generator Phase)

Moderators pin important posts to top:

```json
"reason": {
  "$type": "social.coves.feed.defs#reasonPin",
  "community": {"did": "...", "name": "gaming"}
}
```

### 5. Reply Context

Show post's position in thread:

```json
"reply": {
  "root": {"uri": "at://...", "cid": "..."},
  "parent": {"uri": "at://...", "cid": "..."}
}
```

---

## Lexicon Updates

### Updated: `social.coves.community.post.get`

**Changes:**
1. ✅ Batch URIs: `uri` → `uris[]` (max 25)
2. ✅ Union embed: Matches Bluesky pattern exactly
3. ✅ Error handling: `notFoundPost`, `blockedPost`

**Before:**
```json
{
  "parameters": {
    "uri": "string"
  },
  "output": {
    "post": "#postView"
  }
}
```

**After:**
```json
{
  "parameters": {
    "uris": ["string"]  // Array, max 25
  },
  "output": {
    "posts": [
      "union": ["#postView", "#notFoundPost", "#blockedPost"]
    ]
  }
}
```

**Why?**
- Batch fetching for feed hydration (future)
- Handle missing/blocked posts gracefully
- Bluesky compatibility

### Using: `social.coves.feed.getCommunity`

Already exists, matches our implementation:

```json
{
  "id": "social.coves.feed.getCommunity",
  "parameters": {
    "community": "at-identifier",
    "sort": "hot|top|new",
    "timeframe": "hour|day|week|month|year|all",
    "limit": 1-50,
    "cursor": "string"
  },
  "output": {
    "feed": ["#feedViewPost"],
    "cursor": "string"
  }
}
```

---

## Migration Path

### Alpha → Beta: Adding Feed Generators

**Good news:** No breaking changes needed!

**Approach:**
1. Keep `getCommunity` for standard sorting
2. Add `getFeedSkeleton` for custom algorithms
3. Add `post.get` batch support (already lexicon-ready)
4. Users choose: fast hydrated OR flexible skeleton

**Both coexist:**
```
// Standard community browsing (most users)
GET /xrpc/social.coves.feed.getCommunity?community=gaming&sort=hot
  → One request, hydrated posts

// Custom feed (power users)
GET /xrpc/social.coves.feed.getSkeleton?feed=at://alice/feed/best-memes
  → Returns URIs
GET /xrpc/social.coves.community.post.get?uris=[...]
  → Hydrates posts
```

---

## Success Metrics

### Alpha Launch

- [ ] Users can browse communities
- [ ] Hot/top/new sorting works correctly
- [ ] Pagination stable across 3+ pages
- [ ] Performance < 100ms for 25 posts
- [ ] Handles 1000+ posts per community

### Future KPIs

- Feed load time (target: < 50ms)
- Cache hit rate (future: Redis cache)
- Custom feed adoption (Beta)
- User engagement (time in feed, clicks)

---

## Dependencies

### Required Services

- ✅ PostgreSQL (AppView database)
- ✅ Posts indexed via Jetstream
- ✅ Users indexed via Jetstream
- ✅ Communities indexed via Jetstream

### Optional (Future)

- Redis (feed caching)
- Feed generator services (custom algorithms)

---

## Security Considerations

### Input Validation

- ✅ Community identifier format (DID or handle)
- ✅ Sort parameter (enum: hot/top/new)
- ✅ Limit (1-50, default 15, explicit rejection over 50)
- ✅ Cursor (base64 decoding, format validation)
- ✅ **Cursor injection prevention:**
  - Timestamp format validation (RFC3339Nano)
  - URI format validation (must start with `at://`)
  - Score numeric validation
  - Part count validation (2 for new, 3 for top/hot)

### SQL Injection Prevention

- ✅ All queries use parameterized statements
- ✅ **Dynamic ORDER BY uses whitelist map** (defense-in-depth)
  ```go
  var sortClauses = map[string]string{
      "hot": `(p.score / POWER(...)) DESC, p.created_at DESC`,
      "top": `p.score DESC, p.created_at DESC`,
      "new": `p.created_at DESC, p.uri DESC`,
  }
  ```
- ✅ **Timeframe filter uses hardcoded switch** (no user input in INTERVAL)
- ✅ No string concatenation in SQL

### DoS Prevention

- ✅ **Zero-limit pagination fix:** Guards against `limit=0` causing panic
  - Service layer: Sets default limit if ≤ 0
  - Repository layer: Additional check before array slicing
- ✅ Limit validation: Explicit error for limits over 50
- ✅ Cursor validation: Rejects malformed cursors early

### Rate Limiting

- ✅ Global rate limiter (100 req/min per IP)
- Future: Per-endpoint limits

### Privacy

- Alpha: All feeds public
- Beta: Respect community visibility (private/unlisted)
- Beta: Block lists (hide posts from blocked users)

### Security Audit (PR Review)

All critical and important issues from PR review have been addressed:

**P0 - Critical (Fixed):**
1. ✅ Zero-limit DoS vulnerability
2. ✅ Cursor injection attacks
3. ✅ Validation by-value bug

**Important (Fixed):**
4. ✅ ORDER BY SQL injection hardening
5. ✅ Silent error swallowing in JSON encoding
6. ✅ Limit validation (reject vs silent cap)

**False Positives (Rejected):**
- ❌ Time filter SQL injection (safe by design)
- ❌ Nil pointer dereference (impossible condition)

---

## Conclusion

### What We Shipped

✅ **Complete community feed system (Alpha scope)**
- Hot/top/new sorting algorithms
- Cursor-based pagination
- Single-query performance
- Full post hydration (author, community, stats)
- Error handling
- Production-ready code
- **No viewer state** (YAGNI - deferred to feed generator phase)

### Why It Matters

**Before:** Users could create posts but not see them
**After:** Full community browsing experience

**Impact:**
- 🎯 Core forum functionality
- 🚀 Fast, scalable implementation
- 🔮 Future-proof architecture
- 🤝 Bluesky-compatible patterns

### Next Steps

1. ~~**Write E2E tests**~~ ✅ Complete (8 test cases, all passing)
2. **Performance testing** (1000+ posts under load)
3. **Add to docs site** (API reference)
4. **Monitor in production** (query performance, cursor stability)
5. **PR #2:** Batch `getPosts` for feed generators (Beta)

---

## References

- [PRD: Posts](../PRD_POSTS.md)
- [Lexicon: getCommunity](../internal/atproto/lexicon/social/coves/feed/getCommunity.json)
- [Lexicon: post.get](../internal/atproto/lexicon/social/coves/post/get.json)
- [Bluesky Feed Pattern](https://github.com/bluesky-social/atproto/discussions/4245)
- [Reddit Hot Algorithm](https://medium.com/hacking-and-gonzo/how-reddit-ranking-algorithms-work-ef111e33d0d9)

---

**Document Version:** 1.0
**Last Updated:** October 20, 2025
**Status:** ✅ Implemented, Ready for Testing