+3 -1

.claude/settings.local.json

··· 20 20 "Bash(npm:*)", 21 21 "Bash(docker-compose restart:*)", 22 22 "Bash(echo \"# Bluesky Branding Removal Checklist\n\n## 1. App Icons & Images\n- assets/app-icons/*.png - App icons (replace with Aurora Prism branding)\n- assets/favicon.png - Browser favicon\n- assets/icon-android-*.png - Android icons\n- assets/default-avatar.png - Default avatar image\n\n## 2. App Metadata\n- app.json - App name, slug, description\n- package.json - App name and description\n\n## 3. Text References (276 occurrences)\n- Onboarding screens (src/screens/Onboarding/)\n- Signup screens (src/screens/Signup/)\n- Settings/About screens\n- Terms of Service / Privacy Policy references\n- Help text and tooltips\n- Error messages mentioning Bluesky\n\n## 4. URLs\n- bsky.app references (feed URLs, profile URLs)\n- bsky.social references\n- Links to Bluesky support/help\n\n## 5. Service Names\n- Bluesky Moderation Service references\n- Default feed generator names\n\nTotal: 276 text references found\")", 23 23 - "Bash(psql \"$DATABASE_URL\" -c \"SELECT \n (SELECT COUNT(*) FROM users) as users,\n (SELECT COUNT(*) FROM posts) as posts,\n (SELECT COUNT(*) FROM likes) as likes,\n (SELECT COUNT(*) FROM reposts) as reposts,\n (SELECT COUNT(*) FROM follows) as follows,\n (SELECT COUNT(*) FROM blocks) as blocks;\")" 23 23 + "Bash(psql \"$DATABASE_URL\" -c \"SELECT \n (SELECT COUNT(*) FROM users) as users,\n (SELECT COUNT(*) FROM posts) as posts,\n (SELECT COUNT(*) FROM likes) as likes,\n (SELECT COUNT(*) FROM reposts) as reposts,\n (SELECT COUNT(*) FROM follows) as follows,\n (SELECT COUNT(*) FROM blocks) as blocks;\")", 24 24 + "Bash(dig +short TXT _atproto.spacelawshitpost.me)", 25 25 + "Bash(python3 -m json.tool)" 24 26 ], 25 27 "deny": [], 26 28 "ask": []

+9

.env.example

··· 1 1 # AppView Configuration 2 2 # Copy this to .env and customize as needed 3 3 4 4 + # Relay/Firehose Configuration 5 5 + # Primary relay source (usually Bluesky's main relay) 6 6 + # RELAY_URL=wss://bsky.network/xrpc/com.atproto.sync.subscribeRepos 7 7 + 8 8 + # Additional relay sources (comma-separated) 9 9 + # Use this to crawl independent PDS instances that aren't in Bluesky's relay 10 10 + # Example: atproto.africa hosts blacksky.app and other independent instances 11 11 + # ADDITIONAL_RELAY_URLS=wss://atproto.africa/xrpc/com.atproto.sync.subscribeRepos 12 12 + 4 13 # Constellation Integration (enhanced stats from microcosm.blue) 5 14 # Set to false to disable and avoid timeout errors 6 15 CONSTELLATION_ENABLED=false

+84

ON_DEMAND_PDS_BACKFILL.md

··· 1 1 + # On-Demand PDS Backfill 2 2 + 3 3 + This feature allows your AppView to automatically fetch users from independent PDS instances that aren't federated to Bluesky's relay. 4 4 + 5 5 + ## How It Works 6 6 + 7 7 + ### Automatic Backfill 8 8 + When a user tries to view a profile that doesn't exist in your AppView: 9 9 + 1. The system detects the 404 10 10 + 2. Resolves the user's DID to find their PDS (via plc.directory) 11 11 + 3. Fetches their profile and recent content directly from their PDS 12 12 + 4. Indexes it into your AppView 13 13 + 5. Future requests will return the cached data 14 14 + 15 15 + ### Manual Backfill (Admin Panel) 16 16 + You can also manually trigger backfills via the admin API: 17 17 + 18 18 + ```bash 19 19 + # Trigger backfill for a specific DID 20 20 + curl -X POST https://your-appview.com/api/admin/backfill/pds \ 21 21 + -H "Content-Type: application/json" \ 22 22 + -d '{"did": "did:plc:63hvnyjvqi2nzzcsjgnry5we"}' 23 23 + 24 24 + # Check backfill status 25 25 + curl https://your-appview.com/api/admin/backfill/pds/status 26 26 + ``` 27 27 + 28 28 + ## Example: Backfilling spacelawshitpost.me 29 29 + 30 30 + The user `spacelawshitpost.me` is on blacksky.app PDS and isn't in Bluesky's relay. 31 31 + 32 32 + ### Automatic Method 33 33 + Just try to view their profile in your AppView: 34 34 + ``` 35 35 + GET /xrpc/app.bsky.actor.getProfile?actor=did:plc:63hvnyjvqi2nzzcsjgnry5we 36 36 + ``` 37 37 + 38 38 + First request: Returns 404 with message "Attempting to fetch from their PDS" 39 39 + Wait 5-10 seconds, then retry 40 40 + Second request: Returns full profile! 41 41 + 42 42 + ### Manual Method 43 43 + ```bash 44 44 + curl -X POST https://appview.dollspace.gay/api/admin/backfill/pds \ 45 45 + -H "Content-Type: application/json" \ 46 46 + -d '{"did": "did:plc:63hvnyjvqi2nzzcsjgnry5we"}' 47 47 + ``` 48 48 + 49 49 + ## Rate Limiting 50 50 + 51 51 + - **Cooldown**: 5 minutes per DID (won't re-backfill the same user more frequently) 52 52 + - **Record Limit**: Maximum 1000 records per collection (prevents abuse) 53 53 + 54 54 + ## Collections Backfilled 55 55 + 56 56 + When a user is backfilled, the system fetches: 57 57 + - `app.bsky.actor.profile` - Profile info 58 58 + - `app.bsky.feed.post` - Posts 59 59 + - `app.bsky.feed.like` - Likes 60 60 + - `app.bsky.feed.repost` - Reposts 61 61 + - `app.bsky.graph.follow` - Follows 62 62 + - `app.bsky.graph.block` - Blocks 63 63 + - And any other collections the PDS returns 64 64 + 65 65 + ## Monitoring 66 66 + 67 67 + Check the server logs for backfill progress: 68 68 + ``` 69 69 + [ON_DEMAND_BACKFILL] Starting backfill for did:plc:... 70 70 + [ON_DEMAND_BACKFILL] did:plc:... is on PDS: blacksky.app 71 71 + [ON_DEMAND_BACKFILL] Backfilling spacelawshitpost.me from blacksky.app 72 72 + [ON_DEMAND_BACKFILL] Collections: app.bsky.actor.profile, app.bsky.feed.post, ... 73 73 + [ON_DEMAND_BACKFILL] Backfilled 42 records from app.bsky.feed.post 74 74 + [ON_DEMAND_BACKFILL] Completed backfill for did:plc:... 75 75 + ``` 76 76 + 77 77 + ## Why Is This Needed? 78 78 + 79 79 + Some users are on independent PDS instances that: 80 80 + 1. Aren't federated to Bluesky's main relay 81 81 + 2. Require authentication for firehose access 82 82 + 3. Are on relays that are currently offline (like atproto.africa) 83 83 + 84 84 + This on-demand system ensures your AppView can still serve these users when requested, without continuously polling or maintaining permanent connections to every independent PDS.

+51

server/routes.ts

··· 198 198 `[FIREHOSE] Worker ${workerId}/${totalWorkers} - TypeScript firehose writer (firehose → Redis)` 199 199 ); 200 200 firehoseClient.connect(workerId, totalWorkers); 201 201 + 202 202 + // Connect to additional relay sources (blacksky.app, etc.) 203 203 + const { initializeAdditionalRelays, additionalRelays } = require('./services/firehose'); 204 204 + initializeAdditionalRelays(); 205 205 + 206 206 + if (additionalRelays.length > 0) { 207 207 + console.log(`[FIREHOSE] Connecting to ${additionalRelays.length} additional relay sources...`); 208 208 + additionalRelays.forEach((relay: any, index: number) => { 209 209 + relay.connect(workerId, totalWorkers); 210 210 + console.log(`[FIREHOSE] Additional relay ${index + 1} connected`); 211 211 + }); 212 212 + } 201 213 } else if (!firehoseEnabled) { 202 214 console.log( 203 215 `[FIREHOSE] TypeScript firehose disabled (using Python firehose)` ··· 3421 3433 'TypeScript backfill has been disabled. Please use the Python backfill service instead.', 3422 3434 info: 'Set BACKFILL_DAYS environment variable and run the Python unified worker.', 3423 3435 }); 3436 3436 + }); 3437 3437 + 3438 3438 + // On-demand PDS backfill endpoint 3439 3439 + app.post('/api/admin/backfill/pds', async (req, res) => { 3440 3440 + try { 3441 3441 + const { did } = req.body; 3442 3442 + 3443 3443 + if (!did || !did.startsWith('did:')) { 3444 3444 + res.status(400).json({ error: 'Invalid DID provided' }); 3445 3445 + return; 3446 3446 + } 3447 3447 + 3448 3448 + const { onDemandBackfill } = require('./services/on-demand-backfill'); 3449 3449 + 3450 3450 + // Trigger backfill (non-blocking) 3451 3451 + onDemandBackfill.backfillUser(did).catch((error: any) => { 3452 3452 + console.error(`[API] On-demand backfill failed for ${did}:`, error); 3453 3453 + }); 3454 3454 + 3455 3455 + res.json({ 3456 3456 + success: true, 3457 3457 + message: `Backfill started for ${did}. Check logs for progress.`, 3458 3458 + }); 3459 3459 + } catch (error) { 3460 3460 + console.error('[API] Error triggering on-demand backfill:', error); 3461 3461 + res.status(500).json({ error: 'Failed to trigger backfill' }); 3462 3462 + } 3463 3463 + }); 3464 3464 + 3465 3465 + // Get on-demand backfill status 3466 3466 + app.get('/api/admin/backfill/pds/status', async (_req, res) => { 3467 3467 + try { 3468 3468 + const { onDemandBackfill } = require('./services/on-demand-backfill'); 3469 3469 + const status = onDemandBackfill.getStatus(); 3470 3470 + res.json(status); 3471 3471 + } catch (error) { 3472 3472 + console.error('[API] Error getting backfill status:', error); 3473 3473 + res.status(500).json({ error: 'Failed to get status' }); 3474 3474 + } 3424 3475 }); 3425 3476 3426 3477 // XRPC API Endpoints

+20

server/services/firehose.ts

··· 710 710 } 711 711 712 712 export const firehoseClient = new FirehoseClient(); 713 713 + 714 714 + // Additional relay sources for multi-relay support 715 715 + export const additionalRelays: FirehoseClient[] = []; 716 716 + 717 717 + // Initialize additional relay clients from environment variable 718 718 + export function initializeAdditionalRelays() { 719 719 + const additionalRelayUrls = process.env.ADDITIONAL_RELAY_URLS?.split(',').map(url => url.trim()).filter(Boolean) || []; 720 720 + 721 721 + if (additionalRelayUrls.length > 0) { 722 722 + console.log(`[FIREHOSE] Initializing ${additionalRelayUrls.length} additional relay sources:`, additionalRelayUrls); 723 723 + 724 724 + for (const relayUrl of additionalRelayUrls) { 725 725 + const client = new FirehoseClient(relayUrl); 726 726 + additionalRelays.push(client); 727 727 + console.log(`[FIREHOSE] Additional relay registered: ${relayUrl}`); 728 728 + } 729 729 + } 730 730 + 731 731 + return additionalRelays; 732 732 + }

+232

server/services/on-demand-backfill.ts

··· 1 1 + import { logCollector } from './log-collector'; 2 2 + import { redisQueue } from './redis-queue'; 3 3 + import { metricsService } from './metrics'; 4 4 + 5 5 + interface BackfillJob { 6 6 + did: string; 7 7 + pdsUrl: string; 8 8 + timestamp: number; 9 9 + } 10 10 + 11 11 + export class OnDemandBackfill { 12 12 + private activeJobs: Map<string, BackfillJob> = new Map(); 13 13 + private recentlyBackfilled: Set<string> = new Set(); 14 14 + private readonly BACKFILL_COOLDOWN = 5 * 60 * 1000; // Don't re-backfill same DID for 5 minutes 15 15 + 16 16 + /** 17 17 + * Backfill a user from their PDS when they're not found in our AppView 18 18 + */ 19 19 + async backfillUser(did: string): Promise<boolean> { 20 20 + // Check if we're already backfilling this DID 21 21 + if (this.activeJobs.has(did)) { 22 22 + console.log(`[ON_DEMAND_BACKFILL] Already backfilling ${did}`); 23 23 + return false; 24 24 + } 25 25 + 26 26 + // Check cooldown - don't spam backfill the same user 27 27 + if (this.recentlyBackfilled.has(did)) { 28 28 + console.log(`[ON_DEMAND_BACKFILL] ${did} recently backfilled, skipping`); 29 29 + return false; 30 30 + } 31 31 + 32 32 + try { 33 33 + console.log(`[ON_DEMAND_BACKFILL] Starting backfill for ${did}`); 34 34 + logCollector.info(`On-demand backfill started for ${did}`); 35 35 + 36 36 + // First, resolve the DID to find their PDS 37 37 + const pdsUrl = await this.resolvePDS(did); 38 38 + 39 39 + if (!pdsUrl) { 40 40 + console.warn(`[ON_DEMAND_BACKFILL] Could not resolve PDS for ${did}`); 41 41 + return false; 42 42 + } 43 43 + 44 44 + console.log(`[ON_DEMAND_BACKFILL] ${did} is on PDS: ${pdsUrl}`); 45 45 + 46 46 + // Mark as active 47 47 + this.activeJobs.set(did, { 48 48 + did, 49 49 + pdsUrl, 50 50 + timestamp: Date.now(), 51 51 + }); 52 52 + 53 53 + // Perform the backfill 54 54 + await this.performBackfill(did, pdsUrl); 55 55 + 56 56 + // Mark as recently backfilled (with cooldown) 57 57 + this.recentlyBackfilled.add(did); 58 58 + setTimeout(() => { 59 59 + this.recentlyBackfilled.delete(did); 60 60 + }, this.BACKFILL_COOLDOWN); 61 61 + 62 62 + // Remove from active jobs 63 63 + this.activeJobs.delete(did); 64 64 + 65 65 + console.log(`[ON_DEMAND_BACKFILL] Completed backfill for ${did}`); 66 66 + logCollector.success(`On-demand backfill completed for ${did}`); 67 67 + 68 68 + return true; 69 69 + } catch (error) { 70 70 + console.error(`[ON_DEMAND_BACKFILL] Error backfilling ${did}:`, error); 71 71 + logCollector.error(`On-demand backfill failed for ${did}`, { error }); 72 72 + this.activeJobs.delete(did); 73 73 + metricsService.incrementError(); 74 74 + return false; 75 75 + } 76 76 + } 77 77 + 78 78 + private async resolvePDS(did: string): Promise<string | null> { 79 79 + try { 80 80 + // Fetch DID document from PLC directory 81 81 + const plcUrl = `https://plc.directory/${did}`; 82 82 + const response = await fetch(plcUrl); 83 83 + 84 84 + if (!response.ok) { 85 85 + console.warn(`[ON_DEMAND_BACKFILL] Failed to resolve DID ${did}: ${response.status}`); 86 86 + return null; 87 87 + } 88 88 + 89 89 + const didDoc = await response.json(); 90 90 + 91 91 + // Extract PDS service endpoint 92 92 + const pdsService = didDoc.service?.find( 93 93 + (s: any) => s.type === 'AtprotoPersonalDataServer' 94 94 + ); 95 95 + 96 96 + if (!pdsService?.serviceEndpoint) { 97 97 + console.warn(`[ON_DEMAND_BACKFILL] No PDS service found in DID document for ${did}`); 98 98 + return null; 99 99 + } 100 100 + 101 101 + // Remove https:// prefix to get just the hostname 102 102 + const pdsUrl = pdsService.serviceEndpoint.replace(/^https?:\/\//, ''); 103 103 + 104 104 + return pdsUrl; 105 105 + } catch (error) { 106 106 + console.error(`[ON_DEMAND_BACKFILL] Error resolving PDS for ${did}:`, error); 107 107 + return null; 108 108 + } 109 109 + } 110 110 + 111 111 + private async performBackfill(did: string, pdsUrl: string) { 112 112 + try { 113 113 + // First, get repo description 114 114 + const describeUrl = `https://${pdsUrl}/xrpc/com.atproto.repo.describeRepo?repo=${did}`; 115 115 + const describeResponse = await fetch(describeUrl); 116 116 + 117 117 + if (!describeResponse.ok) { 118 118 + throw new Error(`Failed to describe repo: ${describeResponse.status}`); 119 119 + } 120 120 + 121 121 + const describeData = await describeResponse.json(); 122 122 + const handle = describeData.handle; 123 123 + const collections = describeData.collections || []; 124 124 + 125 125 + console.log(`[ON_DEMAND_BACKFILL] Backfilling ${handle} (${did}) from ${pdsUrl}`); 126 126 + console.log(`[ON_DEMAND_BACKFILL] Collections: ${collections.join(', ')}`); 127 127 + 128 128 + // Process handle/identity first 129 129 + await redisQueue.push({ 130 130 + type: 'identity', 131 131 + data: { 132 132 + did: did, 133 133 + handle: handle, 134 134 + }, 135 135 + }); 136 136 + 137 137 + metricsService.incrementEvent('#identity'); 138 138 + 139 139 + // Backfill each collection 140 140 + for (const collection of collections) { 141 141 + await this.backfillCollection(did, pdsUrl, collection); 142 142 + } 143 143 + 144 144 + console.log(`[ON_DEMAND_BACKFILL] Backfilled all collections for ${did}`); 145 145 + } catch (error) { 146 146 + console.error(`[ON_DEMAND_BACKFILL] Error during backfill:`, error); 147 147 + throw error; 148 148 + } 149 149 + } 150 150 + 151 151 + private async backfillCollection(did: string, pdsUrl: string, collection: string) { 152 152 + try { 153 153 + let cursor: string | undefined = undefined; 154 154 + let totalRecords = 0; 155 155 + 156 156 + do { 157 157 + // Fetch records from this collection 158 158 + const listUrl = `https://${pdsUrl}/xrpc/com.atproto.repo.listRecords?repo=${did}&collection=${collection}&limit=100${cursor ? `&cursor=${cursor}` : ''}`; 159 159 + const response = await fetch(listUrl); 160 160 + 161 161 + if (!response.ok) { 162 162 + if (response.status === 400) { 163 163 + // Collection doesn't exist, skip it 164 164 + return; 165 165 + } 166 166 + throw new Error(`Failed to list ${collection}: ${response.status}`); 167 167 + } 168 168 + 169 169 + const data = await response.json(); 170 170 + const records = data.records || []; 171 171 + 172 172 + if (records.length === 0) { 173 173 + break; 174 174 + } 175 175 + 176 176 + // Process each record 177 177 + for (const record of records) { 178 178 + const path = record.uri.split('/').slice(-2).join('/'); // collection/rkey 179 179 + 180 180 + const commit = { 181 181 + repo: did, 182 182 + ops: [ 183 183 + { 184 184 + action: 'create', 185 185 + path: path, 186 186 + cid: record.cid, 187 187 + record: record.value, 188 188 + }, 189 189 + ], 190 190 + }; 191 191 + 192 192 + // Push to Redis queue for processing 193 193 + await redisQueue.push({ 194 194 + type: 'commit', 195 195 + data: commit, 196 196 + seq: undefined, 197 197 + }); 198 198 + 199 199 + metricsService.incrementEvent('#commit'); 200 200 + totalRecords++; 201 201 + } 202 202 + 203 203 + cursor = data.cursor; 204 204 + 205 205 + // Don't backfill more than 1000 records per collection (prevent abuse) 206 206 + if (totalRecords >= 1000) { 207 207 + console.log(`[ON_DEMAND_BACKFILL] Reached limit of 1000 records for ${collection}, stopping`); 208 208 + break; 209 209 + } 210 210 + 211 211 + } while (cursor); 212 212 + 213 213 + if (totalRecords > 0) { 214 214 + console.log(`[ON_DEMAND_BACKFILL] Backfilled ${totalRecords} records from ${collection}`); 215 215 + } 216 216 + 217 217 + } catch (error) { 218 218 + console.error(`[ON_DEMAND_BACKFILL] Error backfilling collection ${collection}:`, error); 219 219 + throw error; 220 220 + } 221 221 + } 222 222 + 223 223 + getStatus() { 224 224 + return { 225 225 + activeJobs: Array.from(this.activeJobs.values()), 226 226 + recentlyBackfilled: this.recentlyBackfilled.size, 227 227 + cooldownMs: this.BACKFILL_COOLDOWN, 228 228 + }; 229 229 + } 230 230 + } 231 231 + 232 232 + export const onDemandBackfill = new OnDemandBackfill();

+22

server/services/xrpc/services/actor-service.ts

··· 17 17 suggestedUsersUnspeccedSchema, 18 18 } from '../schemas'; 19 19 import { xrpcApi } from '../../xrpc-api'; 20 20 + import { onDemandBackfill } from '../../on-demand-backfill'; 20 21 21 22 /** 22 23 * Get a single actor profile ··· 30 31 const profiles = await (xrpcApi as any)._getProfiles([params.actor], req); 31 32 32 33 if (profiles.length === 0) { 34 34 + // Profile not found - trigger on-demand backfill from their PDS 35 35 + const actor = params.actor; 36 36 + 37 37 + // Check if it's a DID (not a handle) 38 38 + if (actor.startsWith('did:')) { 39 39 + console.log(`[ON_DEMAND] Profile ${actor} not found, triggering backfill...`); 40 40 + 41 41 + // Trigger backfill (non-blocking - don't wait for it) 42 42 + onDemandBackfill.backfillUser(actor).catch(error => { 43 43 + console.error(`[ON_DEMAND] Backfill failed for ${actor}:`, error); 44 44 + }); 45 45 + 46 46 + // Return 404 with a helpful message 47 47 + res.status(404).json({ 48 48 + error: 'ProfileNotFound', 49 49 + message: 'Profile not found. Attempting to fetch from their PDS - try again in a few seconds.', 50 50 + }); 51 51 + return; 52 52 + } 53 53 + 54 54 + // For handles, we'd need to resolve to DID first 33 55 res.status(404).json({ error: 'Profile not found' }); 34 56 return; 35 57 }