mirror of
https://github.com/kennethnym/aris.git
synced 2026-02-02 05:01:17 +00:00
Compare commits
3 Commits
559f82ce96
...
feat/aris-
| Author | SHA1 | Date | |
|---|---|---|---|
| b744af9c51 | |||
| 1893c516f3 | |||
| 181160b018 |
19
apps/aris-backend/package.json
Normal file
19
apps/aris-backend/package.json
Normal file
@@ -0,0 +1,19 @@
|
||||
{
|
||||
"name": "@aris/backend",
|
||||
"version": "0.0.0",
|
||||
"type": "module",
|
||||
"main": "src/index.ts",
|
||||
"scripts": {
|
||||
"dev": "bun run --watch src/index.ts",
|
||||
"start": "bun run src/index.ts",
|
||||
"test": "bun test src/"
|
||||
},
|
||||
"dependencies": {
|
||||
"@aris/core": "workspace:*",
|
||||
"@aris/source-location": "workspace:*",
|
||||
"@aris/source-weatherkit": "workspace:*",
|
||||
"better-auth": "^1",
|
||||
"hono": "^4",
|
||||
"postgres": "^3"
|
||||
}
|
||||
}
|
||||
10
apps/aris-backend/src/index.ts
Normal file
10
apps/aris-backend/src/index.ts
Normal file
@@ -0,0 +1,10 @@
|
||||
import { Hono } from "hono"
|
||||
|
||||
const app = new Hono()
|
||||
|
||||
app.get("/health", (c) => c.json({ status: "ok" }))
|
||||
|
||||
export default {
|
||||
port: 3000,
|
||||
fetch: app.fetch,
|
||||
}
|
||||
7
apps/aris-backend/tsconfig.json
Normal file
7
apps/aris-backend/tsconfig.json
Normal file
@@ -0,0 +1,7 @@
|
||||
{
|
||||
"extends": "../../tsconfig.json",
|
||||
"compilerOptions": {
|
||||
"types": ["bun-types"]
|
||||
},
|
||||
"include": ["src"]
|
||||
}
|
||||
50
bun.lock
50
bun.lock
@@ -13,6 +13,18 @@
|
||||
"typescript": "^5",
|
||||
},
|
||||
},
|
||||
"apps/aris-backend": {
|
||||
"name": "@aris/backend",
|
||||
"version": "0.0.0",
|
||||
"dependencies": {
|
||||
"@aris/core": "workspace:*",
|
||||
"@aris/source-location": "workspace:*",
|
||||
"@aris/source-weatherkit": "workspace:*",
|
||||
"better-auth": "^1",
|
||||
"hono": "^4",
|
||||
"postgres": "^3",
|
||||
},
|
||||
},
|
||||
"packages/aris-core": {
|
||||
"name": "@aris/core",
|
||||
"version": "0.0.0",
|
||||
@@ -51,6 +63,8 @@
|
||||
},
|
||||
},
|
||||
"packages": {
|
||||
"@aris/backend": ["@aris/backend@workspace:apps/aris-backend"],
|
||||
|
||||
"@aris/core": ["@aris/core@workspace:packages/aris-core"],
|
||||
|
||||
"@aris/data-source-tfl": ["@aris/data-source-tfl@workspace:packages/aris-data-source-tfl"],
|
||||
@@ -65,6 +79,18 @@
|
||||
|
||||
"@ark/util": ["@ark/util@0.56.0", "", {}, "sha512-BghfRC8b9pNs3vBoDJhcta0/c1J1rsoS1+HgVUreMFPdhz/CRAKReAu57YEllNaSy98rWAdY1gE+gFup7OXpgA=="],
|
||||
|
||||
"@better-auth/core": ["@better-auth/core@1.4.17", "", { "dependencies": { "@standard-schema/spec": "^1.0.0", "zod": "^4.3.5" }, "peerDependencies": { "@better-auth/utils": "0.3.0", "@better-fetch/fetch": "1.1.21", "better-call": "1.1.8", "jose": "^6.1.0", "kysely": "^0.28.5", "nanostores": "^1.0.1" } }, "sha512-WSaEQDdUO6B1CzAmissN6j0lx9fM9lcslEYzlApB5UzFaBeAOHNUONTdglSyUs6/idiZBoRvt0t/qMXCgIU8ug=="],
|
||||
|
||||
"@better-auth/telemetry": ["@better-auth/telemetry@1.4.17", "", { "dependencies": { "@better-auth/utils": "0.3.0", "@better-fetch/fetch": "1.1.21" }, "peerDependencies": { "@better-auth/core": "1.4.17" } }, "sha512-R1BC4e/bNjQbXu7lG6ubpgmsPj7IMqky5DvMlzAtnAJWJhh99pMh/n6w5gOHa0cqDZgEAuj75IPTxv+q3YiInA=="],
|
||||
|
||||
"@better-auth/utils": ["@better-auth/utils@0.3.0", "", {}, "sha512-W+Adw6ZA6mgvnSnhOki270rwJ42t4XzSK6YWGF//BbVXL6SwCLWfyzBc1lN2m/4RM28KubdBKQ4X5VMoLRNPQw=="],
|
||||
|
||||
"@better-fetch/fetch": ["@better-fetch/fetch@1.1.21", "", {}, "sha512-/ImESw0sskqlVR94jB+5+Pxjf+xBwDZF/N5+y2/q4EqD7IARUTSpPfIo8uf39SYpCxyOCtbyYpUrZ3F/k0zT4A=="],
|
||||
|
||||
"@noble/ciphers": ["@noble/ciphers@2.1.1", "", {}, "sha512-bysYuiVfhxNJuldNXlFEitTVdNnYUc+XNJZd7Qm2a5j1vZHgY+fazadNFWFaMK/2vye0JVlxV3gHmC0WDfAOQw=="],
|
||||
|
||||
"@noble/hashes": ["@noble/hashes@2.0.1", "", {}, "sha512-XlOlEbQcE9fmuXxrVTXCTlG2nlRXa9Rj3rr5Ue/+tX+nmkgbX720YHh0VR3hBF9xDvwnb8D2shVGOwNx+ulArw=="],
|
||||
|
||||
"@oxfmt/darwin-arm64": ["@oxfmt/darwin-arm64@0.24.0", "", { "os": "darwin", "cpu": "arm64" }, "sha512-aYXuGf/yq8nsyEcHindGhiz9I+GEqLkVq8CfPbd+6VE259CpPEH+CaGHEO1j6vIOmNr8KHRq+IAjeRO2uJpb8A=="],
|
||||
|
||||
"@oxfmt/darwin-x64": ["@oxfmt/darwin-x64@0.24.0", "", { "os": "darwin", "cpu": "x64" }, "sha512-vs3b8Bs53hbiNvcNeBilzE/+IhDTWKjSBB3v/ztr664nZk65j0xr+5IHMBNz3CFppmX7o/aBta2PxY+t+4KoPg=="],
|
||||
@@ -97,6 +123,8 @@
|
||||
|
||||
"@oxlint/win32-x64": ["@oxlint/win32-x64@1.39.0", "", { "os": "win32", "cpu": "x64" }, "sha512-sbi25lfj74hH+6qQtb7s1wEvd1j8OQbTaH8v3xTcDjrwm579Cyh0HBv1YSZ2+gsnVwfVDiCTL1D0JsNqYXszVA=="],
|
||||
|
||||
"@standard-schema/spec": ["@standard-schema/spec@1.1.0", "", {}, "sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w=="],
|
||||
|
||||
"@types/bun": ["@types/bun@1.3.6", "", { "dependencies": { "bun-types": "1.3.6" } }, "sha512-uWCv6FO/8LcpREhenN1d1b6fcspAB+cefwD7uti8C8VffIv0Um08TKMn98FynpTiU38+y2dUO55T11NgDt8VAA=="],
|
||||
|
||||
"@types/node": ["@types/node@25.0.9", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-/rpCXHlCWeqClNBwUhDcusJxXYDjZTyE8v5oTO7WbL8eij2nKhUeU89/6xgjU7N4/Vh3He0BtyhJdQbDyhiXAw=="],
|
||||
@@ -105,16 +133,38 @@
|
||||
|
||||
"arktype": ["arktype@2.1.29", "", { "dependencies": { "@ark/schema": "0.56.0", "@ark/util": "0.56.0", "arkregex": "0.0.5" } }, "sha512-jyfKk4xIOzvYNayqnD8ZJQqOwcrTOUbIU4293yrzAjA3O1dWh61j71ArMQ6tS/u4pD7vabSPe7nG3RCyoXW6RQ=="],
|
||||
|
||||
"better-auth": ["better-auth@1.4.17", "", { "dependencies": { "@better-auth/core": "1.4.17", "@better-auth/telemetry": "1.4.17", "@better-auth/utils": "0.3.0", "@better-fetch/fetch": "1.1.21", "@noble/ciphers": "^2.0.0", "@noble/hashes": "^2.0.0", "better-call": "1.1.8", "defu": "^6.1.4", "jose": "^6.1.0", "kysely": "^0.28.5", "nanostores": "^1.0.1", "zod": "^4.3.5" }, "peerDependencies": { "@lynx-js/react": "*", "@prisma/client": "^5.0.0 || ^6.0.0 || ^7.0.0", "@sveltejs/kit": "^2.0.0", "@tanstack/react-start": "^1.0.0", "@tanstack/solid-start": "^1.0.0", "better-sqlite3": "^12.0.0", "drizzle-kit": ">=0.31.4", "drizzle-orm": ">=0.41.0", "mongodb": "^6.0.0 || ^7.0.0", "mysql2": "^3.0.0", "next": "^14.0.0 || ^15.0.0 || ^16.0.0", "pg": "^8.0.0", "prisma": "^5.0.0 || ^6.0.0 || ^7.0.0", "react": "^18.0.0 || ^19.0.0", "react-dom": "^18.0.0 || ^19.0.0", "solid-js": "^1.0.0", "svelte": "^4.0.0 || ^5.0.0", "vitest": "^2.0.0 || ^3.0.0 || ^4.0.0", "vue": "^3.0.0" }, "optionalPeers": ["@lynx-js/react", "@prisma/client", "@sveltejs/kit", "@tanstack/react-start", "@tanstack/solid-start", "better-sqlite3", "drizzle-kit", "drizzle-orm", "mongodb", "mysql2", "next", "pg", "prisma", "react", "react-dom", "solid-js", "svelte", "vitest", "vue"] }, "sha512-VmHGQyKsEahkEs37qguROKg/6ypYpNF13D7v/lkbO7w7Aivz0Bv2h+VyUkH4NzrGY0QBKXi1577mGhDCVwp0ew=="],
|
||||
|
||||
"better-call": ["better-call@1.1.8", "", { "dependencies": { "@better-auth/utils": "^0.3.0", "@better-fetch/fetch": "^1.1.4", "rou3": "^0.7.10", "set-cookie-parser": "^2.7.1" }, "peerDependencies": { "zod": "^4.0.0" }, "optionalPeers": ["zod"] }, "sha512-XMQ2rs6FNXasGNfMjzbyroSwKwYbZ/T3IxruSS6U2MJRsSYh3wYtG3o6H00ZlKZ/C/UPOAD97tqgQJNsxyeTXw=="],
|
||||
|
||||
"bun-types": ["bun-types@1.3.6", "", { "dependencies": { "@types/node": "*" } }, "sha512-OlFwHcnNV99r//9v5IIOgQ9Uk37gZqrNMCcqEaExdkVq3Avwqok1bJFmvGMCkCE0FqzdY8VMOZpfpR3lwI+CsQ=="],
|
||||
|
||||
"defu": ["defu@6.1.4", "", {}, "sha512-mEQCMmwJu317oSz8CwdIOdwf3xMif1ttiM8LTufzc3g6kR+9Pe236twL8j3IYT1F7GfRgGcW6MWxzZjLIkuHIg=="],
|
||||
|
||||
"hono": ["hono@4.11.5", "", {}, "sha512-WemPi9/WfyMwZs+ZUXdiwcCh9Y+m7L+8vki9MzDw3jJ+W9Lc+12HGsd368Qc1vZi1xwW8BWMMsnK5efYKPdt4g=="],
|
||||
|
||||
"jose": ["jose@6.1.3", "", {}, "sha512-0TpaTfihd4QMNwrz/ob2Bp7X04yuxJkjRGi4aKmOqwhov54i6u79oCv7T+C7lo70MKH6BesI3vscD1yb/yzKXQ=="],
|
||||
|
||||
"kysely": ["kysely@0.28.10", "", {}, "sha512-ksNxfzIW77OcZ+QWSAPC7yDqUSaIVwkTWnTPNiIy//vifNbwsSgQ57OkkncHxxpcBHM3LRfLAZVEh7kjq5twVA=="],
|
||||
|
||||
"nanostores": ["nanostores@1.1.0", "", {}, "sha512-yJBmDJr18xy47dbNVlHcgdPrulSn1nhSE6Ns9vTG+Nx9VPT6iV1MD6aQFp/t52zpf82FhLLTXAXr30NuCnxvwA=="],
|
||||
|
||||
"oxfmt": ["oxfmt@0.24.0", "", { "dependencies": { "tinypool": "2.0.0" }, "optionalDependencies": { "@oxfmt/darwin-arm64": "0.24.0", "@oxfmt/darwin-x64": "0.24.0", "@oxfmt/linux-arm64-gnu": "0.24.0", "@oxfmt/linux-arm64-musl": "0.24.0", "@oxfmt/linux-x64-gnu": "0.24.0", "@oxfmt/linux-x64-musl": "0.24.0", "@oxfmt/win32-arm64": "0.24.0", "@oxfmt/win32-x64": "0.24.0" }, "bin": { "oxfmt": "bin/oxfmt" } }, "sha512-UjeM3Peez8Tl7IJ9s5UwAoZSiDRMww7BEc21gDYxLq3S3/KqJnM3mjNxsoSHgmBvSeX6RBhoVc2MfC/+96RdSw=="],
|
||||
|
||||
"oxlint": ["oxlint@1.39.0", "", { "optionalDependencies": { "@oxlint/darwin-arm64": "1.39.0", "@oxlint/darwin-x64": "1.39.0", "@oxlint/linux-arm64-gnu": "1.39.0", "@oxlint/linux-arm64-musl": "1.39.0", "@oxlint/linux-x64-gnu": "1.39.0", "@oxlint/linux-x64-musl": "1.39.0", "@oxlint/win32-arm64": "1.39.0", "@oxlint/win32-x64": "1.39.0" }, "peerDependencies": { "oxlint-tsgolint": ">=0.10.0" }, "optionalPeers": ["oxlint-tsgolint"], "bin": { "oxlint": "bin/oxlint" } }, "sha512-wSiLr0wjG+KTU6c1LpVoQk7JZ7l8HCKlAkVDVTJKWmCGazsNxexxnOXl7dsar92mQcRnzko5g077ggP3RINSjA=="],
|
||||
|
||||
"postgres": ["postgres@3.4.8", "", {}, "sha512-d+JFcLM17njZaOLkv6SCev7uoLaBtfK86vMUXhW1Z4glPWh4jozno9APvW/XKFJ3CCxVoC7OL38BqRydtu5nGg=="],
|
||||
|
||||
"rou3": ["rou3@0.7.12", "", {}, "sha512-iFE4hLDuloSWcD7mjdCDhx2bKcIsYbtOTpfH5MHHLSKMOUyjqQXTeZVa289uuwEGEKFoE/BAPbhaU4B774nceg=="],
|
||||
|
||||
"set-cookie-parser": ["set-cookie-parser@2.7.2", "", {}, "sha512-oeM1lpU/UvhTxw+g3cIfxXHyJRc/uidd3yK1P242gzHds0udQBYzs3y8j4gCCW+ZJ7ad0yctld8RYO+bdurlvw=="],
|
||||
|
||||
"tinypool": ["tinypool@2.0.0", "", {}, "sha512-/RX9RzeH2xU5ADE7n2Ykvmi9ED3FBGPAjw9u3zucrNNaEBIO0HPSYgL0NT7+3p147ojeSdaVu08F6hjpv31HJg=="],
|
||||
|
||||
"typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
|
||||
|
||||
"undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
|
||||
|
||||
"zod": ["zod@4.3.6", "", {}, "sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg=="],
|
||||
}
|
||||
}
|
||||
|
||||
178
docs/backend-spec.md
Normal file
178
docs/backend-spec.md
Normal file
@@ -0,0 +1,178 @@
|
||||
# ARIS Backend Specification
|
||||
|
||||
## Problem Statement
|
||||
|
||||
ARIS needs a backend service that manages per-user FeedEngine instances and delivers real-time feed updates to clients. The backend must handle authentication, maintain WebSocket connections for live updates, and accept context updates (like location) that trigger feed recalculations.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Authentication
|
||||
- Email/password authentication using BetterAuth
|
||||
- PostgreSQL for session and user storage
|
||||
- Session tokens validated via `Authorization: Bearer <token>` header
|
||||
- Auth endpoints exposed via BetterAuth's built-in routes
|
||||
|
||||
### FeedEngine Management
|
||||
- Each authenticated user gets their own FeedEngine instance
|
||||
- Instances are cached in memory with a 30-minute TTL
|
||||
- TTL resets on any activity (WebSocket message, location update)
|
||||
- Default sources registered for each user: `LocationSource`, `WeatherSource`, `TflSource`
|
||||
- Source configuration is hardcoded initially (customization deferred)
|
||||
|
||||
### WebSocket Connection
|
||||
- Single endpoint: `GET /ws` (upgrades to WebSocket)
|
||||
- Authentication via `Authorization: Bearer <token>` header on upgrade request
|
||||
- Rejected before upgrade if token is invalid
|
||||
- Multiple connections per user allowed (e.g., multiple devices)
|
||||
- All connections for a user receive the same feed updates
|
||||
- On connect: immediately send current feed state
|
||||
|
||||
### JSON-RPC Protocol
|
||||
All WebSocket communication uses JSON-RPC 2.0.
|
||||
|
||||
**Client → Server (Requests):**
|
||||
```json
|
||||
{ "jsonrpc": "2.0", "method": "location.update", "params": { "lat": 51.5, "lng": -0.1, "accuracy": 10, "timestamp": "2025-01-01T12:00:00Z" }, "id": 1 }
|
||||
{ "jsonrpc": "2.0", "method": "feed.refresh", "params": {}, "id": 2 }
|
||||
```
|
||||
|
||||
**Server → Client (Responses):**
|
||||
```json
|
||||
{ "jsonrpc": "2.0", "result": { "ok": true }, "id": 1 }
|
||||
```
|
||||
|
||||
**Server → Client (Notifications - no id):**
|
||||
```json
|
||||
{ "jsonrpc": "2.0", "method": "feed.update", "params": { "items": [...], "errors": [...] } }
|
||||
```
|
||||
|
||||
### JSON-RPC Methods
|
||||
|
||||
| Method | Params | Description |
|
||||
|--------|--------|-------------|
|
||||
| `location.update` | `{ lat, lng, accuracy, timestamp }` | Push location update, triggers feed refresh |
|
||||
| `feed.refresh` | `{}` | Force manual feed refresh |
|
||||
|
||||
### Server Notifications
|
||||
|
||||
| Method | Params | Description |
|
||||
|--------|--------|-------------|
|
||||
| `feed.update` | `{ context, items, errors }` | Feed state changed |
|
||||
| `error` | `{ code, message, data? }` | Source or system error |
|
||||
|
||||
### Error Handling
|
||||
- Source failures during refresh are reported via `error` notification
|
||||
- Format: `{ "jsonrpc": "2.0", "method": "error", "params": { "code": -32000, "message": "...", "data": { "sourceId": "weather" } } }`
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
1. **Auth Flow**
|
||||
- [ ] User can sign up with email/password via `POST /api/auth/sign-up`
|
||||
- [ ] User can sign in via `POST /api/auth/sign-in` and receive session token
|
||||
- [ ] Invalid credentials return 401
|
||||
|
||||
2. **WebSocket Connection**
|
||||
- [ ] `GET /ws` with valid `Authorization` header upgrades to WebSocket
|
||||
- [ ] `GET /ws` without valid token returns 401 (no upgrade)
|
||||
- [ ] On successful connect, client receives `feed.update` notification with current state
|
||||
- [ ] Multiple connections from same user all receive updates
|
||||
|
||||
3. **FeedEngine Lifecycle**
|
||||
- [ ] First connection for a user creates FeedEngine with default sources
|
||||
- [ ] Subsequent connections reuse the same FeedEngine
|
||||
- [ ] FeedEngine is destroyed after 30 minutes of inactivity
|
||||
- [ ] Activity (any WebSocket message) resets the TTL
|
||||
|
||||
4. **JSON-RPC Methods**
|
||||
- [ ] `location.update` updates LocationSource and triggers feed refresh
|
||||
- [ ] `feed.refresh` triggers manual refresh
|
||||
- [ ] Both return `{ "ok": true }` on success
|
||||
- [ ] Invalid method returns JSON-RPC error
|
||||
|
||||
5. **Feed Updates**
|
||||
- [ ] FeedEngine subscription pushes updates to all user's WebSocket connections
|
||||
- [ ] Updates include `context`, `items`, and `errors`
|
||||
|
||||
## Implementation Approach
|
||||
|
||||
### Phase 1: Project Setup
|
||||
1. Create `apps/aris-backend` with Hono
|
||||
2. Configure TypeScript, add dependencies (hono, better-auth, postgres driver)
|
||||
3. Set up database connection and BetterAuth
|
||||
|
||||
### Phase 2: Authentication
|
||||
4. Configure BetterAuth with email/password provider
|
||||
5. Mount BetterAuth routes at `/api/auth/*`
|
||||
6. Create session validation helper for extracting user from token
|
||||
|
||||
### Phase 3: FeedEngine Manager
|
||||
7. Create `FeedEngineManager` class:
|
||||
- `getOrCreate(userId): FeedEngine` - returns cached or creates new
|
||||
- `touch(userId)` - resets TTL
|
||||
- `destroy(userId)` - manual cleanup
|
||||
- Internal TTL cleanup loop
|
||||
8. Factory function to create FeedEngine with default sources
|
||||
|
||||
### Phase 4: WebSocket Handler
|
||||
9. Create WebSocket upgrade endpoint at `/ws`
|
||||
10. Validate `Authorization` header before upgrade
|
||||
11. On connect: register connection, send initial feed state
|
||||
12. On disconnect: unregister connection
|
||||
|
||||
### Phase 5: JSON-RPC Handler
|
||||
13. Create JSON-RPC message parser and dispatcher
|
||||
14. Implement `location.update` method
|
||||
15. Implement `feed.refresh` method
|
||||
16. Wire FeedEngine subscription to broadcast `feed.update` to all user connections
|
||||
|
||||
### Phase 6: Connection Manager
|
||||
17. Create `ConnectionManager` to track WebSocket connections per user
|
||||
18. Broadcast helper to send to all connections for a user
|
||||
|
||||
### Phase 7: Integration & Testing
|
||||
19. Integration test: auth → connect → location update → receive feed
|
||||
20. Test multiple connections receive same updates
|
||||
21. Test TTL cleanup
|
||||
|
||||
## Package Structure
|
||||
|
||||
```
|
||||
apps/aris-backend/
|
||||
├── package.json
|
||||
├── src/
|
||||
│ ├── index.ts # Entry point, Hono app
|
||||
│ ├── auth.ts # BetterAuth configuration
|
||||
│ ├── db.ts # Database connection
|
||||
│ ├── ws/
|
||||
│ │ ├── handler.ts # WebSocket upgrade & message handling
|
||||
│ │ ├── jsonrpc.ts # JSON-RPC parser & types
|
||||
│ │ └── methods.ts # Method implementations
|
||||
│ ├── feed/
|
||||
│ │ ├── manager.ts # FeedEngineManager (TTL cache)
|
||||
│ │ ├── factory.ts # Creates FeedEngine with default sources
|
||||
│ │ └── connections.ts # ConnectionManager (user → WebSocket[])
|
||||
│ └── types.ts # Shared types
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
|
||||
```json
|
||||
{
|
||||
"dependencies": {
|
||||
"hono": "^4",
|
||||
"better-auth": "^1",
|
||||
"postgres": "^3",
|
||||
"@aris/core": "workspace:*",
|
||||
"@aris/source-location": "workspace:*",
|
||||
"@aris/source-weatherkit": "workspace:*",
|
||||
"@aris/data-source-tfl": "workspace:*"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Open Questions (Deferred)
|
||||
|
||||
- User source configuration storage (database schema)
|
||||
- Rate limiting on WebSocket methods
|
||||
- Reconnection handling (client-side concern)
|
||||
- Horizontal scaling (would need Redis for shared state)
|
||||
458
packages/aris-core/src/feed-engine.test.ts
Normal file
458
packages/aris-core/src/feed-engine.test.ts
Normal file
@@ -0,0 +1,458 @@
|
||||
import { describe, expect, test } from "bun:test"
|
||||
|
||||
import type { Context, ContextKey, FeedItem, FeedSource } from "./index"
|
||||
|
||||
import { FeedEngine } from "./feed-engine"
|
||||
import { contextKey, contextValue } from "./index"
|
||||
|
||||
// =============================================================================
|
||||
// CONTEXT KEYS
|
||||
// =============================================================================
|
||||
|
||||
interface Location {
|
||||
lat: number
|
||||
lng: number
|
||||
}
|
||||
|
||||
interface Weather {
|
||||
temperature: number
|
||||
condition: string
|
||||
}
|
||||
|
||||
const LocationKey: ContextKey<Location> = contextKey("location")
|
||||
const WeatherKey: ContextKey<Weather> = contextKey("weather")
|
||||
|
||||
// =============================================================================
|
||||
// FEED ITEMS
|
||||
// =============================================================================
|
||||
|
||||
type WeatherFeedItem = FeedItem<"weather", { temperature: number; condition: string }>
|
||||
type AlertFeedItem = FeedItem<"alert", { message: string }>
|
||||
|
||||
// =============================================================================
|
||||
// TEST HELPERS
|
||||
// =============================================================================
|
||||
|
||||
interface SimulatedLocationSource extends FeedSource {
|
||||
simulateUpdate(location: Location): void
|
||||
}
|
||||
|
||||
function createLocationSource(): SimulatedLocationSource {
|
||||
let callback: ((update: Partial<Context>) => void) | null = null
|
||||
let currentLocation: Location = { lat: 0, lng: 0 }
|
||||
|
||||
return {
|
||||
id: "location",
|
||||
|
||||
onContextUpdate(cb) {
|
||||
callback = cb
|
||||
return () => {
|
||||
callback = null
|
||||
}
|
||||
},
|
||||
|
||||
async fetchContext() {
|
||||
return { [LocationKey]: currentLocation }
|
||||
},
|
||||
|
||||
simulateUpdate(location: Location) {
|
||||
currentLocation = location
|
||||
callback?.({ [LocationKey]: location })
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
function createWeatherSource(
|
||||
fetchWeather: (location: Location) => Promise<Weather> = async () => ({
|
||||
temperature: 20,
|
||||
condition: "sunny",
|
||||
}),
|
||||
): FeedSource<WeatherFeedItem> {
|
||||
return {
|
||||
id: "weather",
|
||||
dependencies: ["location"],
|
||||
|
||||
async fetchContext(context) {
|
||||
const location = contextValue(context, LocationKey)
|
||||
if (!location) return {}
|
||||
|
||||
const weather = await fetchWeather(location)
|
||||
return { [WeatherKey]: weather }
|
||||
},
|
||||
|
||||
async fetchItems(context) {
|
||||
const weather = contextValue(context, WeatherKey)
|
||||
if (!weather) return []
|
||||
|
||||
return [
|
||||
{
|
||||
id: `weather-${Date.now()}`,
|
||||
type: "weather",
|
||||
priority: 0.5,
|
||||
timestamp: new Date(),
|
||||
data: {
|
||||
temperature: weather.temperature,
|
||||
condition: weather.condition,
|
||||
},
|
||||
},
|
||||
]
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
function createAlertSource(): FeedSource<AlertFeedItem> {
|
||||
return {
|
||||
id: "alert",
|
||||
dependencies: ["weather"],
|
||||
|
||||
async fetchItems(context) {
|
||||
const weather = contextValue(context, WeatherKey)
|
||||
if (!weather) return []
|
||||
|
||||
if (weather.condition === "storm") {
|
||||
return [
|
||||
{
|
||||
id: "alert-storm",
|
||||
type: "alert",
|
||||
priority: 1.0,
|
||||
timestamp: new Date(),
|
||||
data: { message: "Storm warning!" },
|
||||
},
|
||||
]
|
||||
}
|
||||
|
||||
return []
|
||||
},
|
||||
}
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// TESTS
|
||||
// =============================================================================
|
||||
|
||||
describe("FeedEngine", () => {
|
||||
describe("registration", () => {
|
||||
test("registers sources", () => {
|
||||
const engine = new FeedEngine()
|
||||
const location = createLocationSource()
|
||||
|
||||
engine.register(location)
|
||||
|
||||
// Can refresh without error
|
||||
expect(engine.refresh()).resolves.toBeDefined()
|
||||
})
|
||||
|
||||
test("unregisters sources", async () => {
|
||||
const engine = new FeedEngine()
|
||||
const location = createLocationSource()
|
||||
|
||||
engine.register(location)
|
||||
engine.unregister("location")
|
||||
|
||||
const result = await engine.refresh()
|
||||
expect(result.items).toHaveLength(0)
|
||||
})
|
||||
|
||||
test("allows chained registration", () => {
|
||||
const engine = new FeedEngine()
|
||||
.register(createLocationSource())
|
||||
.register(createWeatherSource())
|
||||
.register(createAlertSource())
|
||||
|
||||
expect(engine.refresh()).resolves.toBeDefined()
|
||||
})
|
||||
})
|
||||
|
||||
describe("graph validation", () => {
|
||||
test("throws on missing dependency", () => {
|
||||
const engine = new FeedEngine()
|
||||
const orphan: FeedSource = {
|
||||
id: "orphan",
|
||||
dependencies: ["nonexistent"],
|
||||
}
|
||||
|
||||
engine.register(orphan)
|
||||
|
||||
expect(engine.refresh()).rejects.toThrow(
|
||||
'Source "orphan" depends on "nonexistent" which is not registered',
|
||||
)
|
||||
})
|
||||
|
||||
test("throws on circular dependency", () => {
|
||||
const engine = new FeedEngine()
|
||||
const a: FeedSource = { id: "a", dependencies: ["b"] }
|
||||
const b: FeedSource = { id: "b", dependencies: ["a"] }
|
||||
|
||||
engine.register(a).register(b)
|
||||
|
||||
expect(engine.refresh()).rejects.toThrow("Circular dependency detected: a → b → a")
|
||||
})
|
||||
|
||||
test("throws on longer cycles", () => {
|
||||
const engine = new FeedEngine()
|
||||
const a: FeedSource = { id: "a", dependencies: ["c"] }
|
||||
const b: FeedSource = { id: "b", dependencies: ["a"] }
|
||||
const c: FeedSource = { id: "c", dependencies: ["b"] }
|
||||
|
||||
engine.register(a).register(b).register(c)
|
||||
|
||||
expect(engine.refresh()).rejects.toThrow("Circular dependency detected")
|
||||
})
|
||||
})
|
||||
|
||||
describe("refresh", () => {
|
||||
test("runs fetchContext in dependency order", async () => {
|
||||
const order: string[] = []
|
||||
|
||||
const location: FeedSource = {
|
||||
id: "location",
|
||||
async fetchContext() {
|
||||
order.push("location")
|
||||
return { [LocationKey]: { lat: 51.5, lng: -0.1 } }
|
||||
},
|
||||
}
|
||||
|
||||
const weather: FeedSource = {
|
||||
id: "weather",
|
||||
dependencies: ["location"],
|
||||
async fetchContext(ctx) {
|
||||
order.push("weather")
|
||||
const loc = contextValue(ctx, LocationKey)
|
||||
expect(loc).toBeDefined()
|
||||
return { [WeatherKey]: { temperature: 20, condition: "sunny" } }
|
||||
},
|
||||
}
|
||||
|
||||
const engine = new FeedEngine().register(weather).register(location)
|
||||
|
||||
await engine.refresh()
|
||||
|
||||
expect(order).toEqual(["location", "weather"])
|
||||
})
|
||||
|
||||
test("accumulates context across sources", async () => {
|
||||
const location = createLocationSource()
|
||||
location.simulateUpdate({ lat: 51.5, lng: -0.1 })
|
||||
|
||||
const weather = createWeatherSource()
|
||||
|
||||
const engine = new FeedEngine().register(location).register(weather)
|
||||
|
||||
const { context } = await engine.refresh()
|
||||
|
||||
expect(contextValue(context, LocationKey)).toEqual({ lat: 51.5, lng: -0.1 })
|
||||
expect(contextValue(context, WeatherKey)).toEqual({ temperature: 20, condition: "sunny" })
|
||||
})
|
||||
|
||||
test("collects items from all sources", async () => {
|
||||
const location = createLocationSource()
|
||||
location.simulateUpdate({ lat: 51.5, lng: -0.1 })
|
||||
|
||||
const weather = createWeatherSource()
|
||||
|
||||
const engine = new FeedEngine().register(location).register(weather)
|
||||
|
||||
const { items } = await engine.refresh()
|
||||
|
||||
expect(items).toHaveLength(1)
|
||||
expect(items[0]!.type).toBe("weather")
|
||||
})
|
||||
|
||||
test("sorts items by priority descending", async () => {
|
||||
const location = createLocationSource()
|
||||
location.simulateUpdate({ lat: 51.5, lng: -0.1 })
|
||||
|
||||
const weather = createWeatherSource(async () => ({
|
||||
temperature: 15,
|
||||
condition: "storm",
|
||||
}))
|
||||
|
||||
const alert = createAlertSource()
|
||||
|
||||
const engine = new FeedEngine().register(location).register(weather).register(alert)
|
||||
|
||||
const { items } = await engine.refresh()
|
||||
|
||||
expect(items).toHaveLength(2)
|
||||
expect(items[0]!.type).toBe("alert") // priority 1.0
|
||||
expect(items[1]!.type).toBe("weather") // priority 0.5
|
||||
})
|
||||
|
||||
test("handles missing upstream context gracefully", async () => {
|
||||
const location: FeedSource = {
|
||||
id: "location",
|
||||
async fetchContext() {
|
||||
return {} // No location available
|
||||
},
|
||||
}
|
||||
|
||||
const weather = createWeatherSource()
|
||||
|
||||
const engine = new FeedEngine().register(location).register(weather)
|
||||
|
||||
const { context, items } = await engine.refresh()
|
||||
|
||||
expect(contextValue(context, WeatherKey)).toBeUndefined()
|
||||
expect(items).toHaveLength(0)
|
||||
})
|
||||
|
||||
test("captures errors from fetchContext", async () => {
|
||||
const failing: FeedSource = {
|
||||
id: "failing",
|
||||
async fetchContext() {
|
||||
throw new Error("Context fetch failed")
|
||||
},
|
||||
}
|
||||
|
||||
const engine = new FeedEngine().register(failing)
|
||||
|
||||
const { errors } = await engine.refresh()
|
||||
|
||||
expect(errors).toHaveLength(1)
|
||||
expect(errors[0]!.sourceId).toBe("failing")
|
||||
expect(errors[0]!.error.message).toBe("Context fetch failed")
|
||||
})
|
||||
|
||||
test("captures errors from fetchItems", async () => {
|
||||
const failing: FeedSource = {
|
||||
id: "failing",
|
||||
async fetchItems() {
|
||||
throw new Error("Items fetch failed")
|
||||
},
|
||||
}
|
||||
|
||||
const engine = new FeedEngine().register(failing)
|
||||
|
||||
const { errors } = await engine.refresh()
|
||||
|
||||
expect(errors).toHaveLength(1)
|
||||
expect(errors[0]!.sourceId).toBe("failing")
|
||||
expect(errors[0]!.error.message).toBe("Items fetch failed")
|
||||
})
|
||||
|
||||
test("continues after source error", async () => {
|
||||
const failing: FeedSource = {
|
||||
id: "failing",
|
||||
async fetchContext() {
|
||||
throw new Error("Failed")
|
||||
},
|
||||
}
|
||||
|
||||
const working: FeedSource = {
|
||||
id: "working",
|
||||
async fetchItems() {
|
||||
return [
|
||||
{
|
||||
id: "item-1",
|
||||
type: "test",
|
||||
priority: 0.5,
|
||||
timestamp: new Date(),
|
||||
data: {},
|
||||
},
|
||||
]
|
||||
},
|
||||
}
|
||||
|
||||
const engine = new FeedEngine().register(failing).register(working)
|
||||
|
||||
const { items, errors } = await engine.refresh()
|
||||
|
||||
expect(errors).toHaveLength(1)
|
||||
expect(items).toHaveLength(1)
|
||||
})
|
||||
})
|
||||
|
||||
describe("currentContext", () => {
|
||||
test("returns initial context before refresh", () => {
|
||||
const engine = new FeedEngine()
|
||||
|
||||
const context = engine.currentContext()
|
||||
|
||||
expect(context.time).toBeInstanceOf(Date)
|
||||
})
|
||||
|
||||
test("returns accumulated context after refresh", async () => {
|
||||
const location = createLocationSource()
|
||||
location.simulateUpdate({ lat: 51.5, lng: -0.1 })
|
||||
|
||||
const engine = new FeedEngine().register(location)
|
||||
|
||||
await engine.refresh()
|
||||
|
||||
const context = engine.currentContext()
|
||||
expect(contextValue(context, LocationKey)).toEqual({ lat: 51.5, lng: -0.1 })
|
||||
})
|
||||
})
|
||||
|
||||
describe("subscribe", () => {
|
||||
test("returns unsubscribe function", () => {
|
||||
const engine = new FeedEngine()
|
||||
let callCount = 0
|
||||
|
||||
const unsubscribe = engine.subscribe(() => {
|
||||
callCount++
|
||||
})
|
||||
|
||||
unsubscribe()
|
||||
|
||||
// Subscriber should not be called after unsubscribe
|
||||
expect(callCount).toBe(0)
|
||||
})
|
||||
})
|
||||
|
||||
describe("reactive updates", () => {
|
||||
test("start subscribes to onContextUpdate", async () => {
|
||||
const location = createLocationSource()
|
||||
const weather = createWeatherSource()
|
||||
|
||||
const engine = new FeedEngine().register(location).register(weather)
|
||||
|
||||
const results: Array<{ items: FeedItem[] }> = []
|
||||
engine.subscribe((result) => {
|
||||
results.push({ items: result.items })
|
||||
})
|
||||
|
||||
engine.start()
|
||||
|
||||
// Simulate location update
|
||||
location.simulateUpdate({ lat: 51.5, lng: -0.1 })
|
||||
|
||||
// Wait for async refresh
|
||||
await new Promise((resolve) => setTimeout(resolve, 50))
|
||||
|
||||
expect(results.length).toBeGreaterThan(0)
|
||||
expect(results[0]!.items[0]!.type).toBe("weather")
|
||||
})
|
||||
|
||||
test("stop unsubscribes from all sources", async () => {
|
||||
const location = createLocationSource()
|
||||
|
||||
const engine = new FeedEngine().register(location)
|
||||
|
||||
let callCount = 0
|
||||
engine.subscribe(() => {
|
||||
callCount++
|
||||
})
|
||||
|
||||
engine.start()
|
||||
engine.stop()
|
||||
|
||||
// Simulate update after stop
|
||||
location.simulateUpdate({ lat: 1, lng: 1 })
|
||||
|
||||
await new Promise((resolve) => setTimeout(resolve, 50))
|
||||
|
||||
expect(callCount).toBe(0)
|
||||
})
|
||||
|
||||
test("start is idempotent", () => {
|
||||
const location = createLocationSource()
|
||||
const engine = new FeedEngine().register(location)
|
||||
|
||||
// Should not throw or double-subscribe
|
||||
engine.start()
|
||||
engine.start()
|
||||
engine.stop()
|
||||
})
|
||||
})
|
||||
})
|
||||
335
packages/aris-core/src/feed-engine.ts
Normal file
335
packages/aris-core/src/feed-engine.ts
Normal file
@@ -0,0 +1,335 @@
|
||||
import type { Context } from "./context"
|
||||
import type { FeedItem } from "./feed"
|
||||
import type { FeedSource } from "./feed-source"
|
||||
|
||||
export interface SourceError {
|
||||
sourceId: string
|
||||
error: Error
|
||||
}
|
||||
|
||||
export interface FeedResult<TItem extends FeedItem = FeedItem> {
|
||||
context: Context
|
||||
items: TItem[]
|
||||
errors: SourceError[]
|
||||
}
|
||||
|
||||
export type FeedSubscriber<TItem extends FeedItem = FeedItem> = (result: FeedResult<TItem>) => void
|
||||
|
||||
interface SourceGraph {
|
||||
sources: Map<string, FeedSource>
|
||||
sorted: FeedSource[]
|
||||
dependents: Map<string, string[]>
|
||||
}
|
||||
|
||||
/**
|
||||
* Orchestrates FeedSources, managing the dependency graph and context flow.
|
||||
*
|
||||
* Sources declare dependencies on other sources. The engine:
|
||||
* - Validates the dependency graph (no missing deps, no cycles)
|
||||
* - Runs fetchContext() in topological order during refresh
|
||||
* - Runs fetchItems() on all sources with accumulated context
|
||||
* - Subscribes to reactive updates via onContextUpdate/onItemsUpdate
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* const engine = new FeedEngine()
|
||||
* .register(locationSource)
|
||||
* .register(weatherSource)
|
||||
* .register(alertSource)
|
||||
*
|
||||
* // Pull-based refresh
|
||||
* const { context, items, errors } = await engine.refresh()
|
||||
*
|
||||
* // Reactive updates
|
||||
* engine.subscribe((result) => {
|
||||
* console.log(result.items)
|
||||
* })
|
||||
* engine.start()
|
||||
*
|
||||
* // Cleanup
|
||||
* engine.stop()
|
||||
* ```
|
||||
*/
|
||||
export class FeedEngine<TItems extends FeedItem = FeedItem> {
|
||||
private sources = new Map<string, FeedSource>()
|
||||
private graph: SourceGraph | null = null
|
||||
private context: Context = { time: new Date() }
|
||||
private subscribers = new Set<FeedSubscriber<TItems>>()
|
||||
private cleanups: Array<() => void> = []
|
||||
private started = false
|
||||
|
||||
/**
|
||||
* Registers a FeedSource. Invalidates the cached graph.
|
||||
*/
|
||||
register<TItem extends FeedItem>(source: FeedSource<TItem>): FeedEngine<TItems | TItem> {
|
||||
this.sources.set(source.id, source)
|
||||
this.graph = null
|
||||
return this as FeedEngine<TItems | TItem>
|
||||
}
|
||||
|
||||
/**
|
||||
* Unregisters a FeedSource by ID. Invalidates the cached graph.
|
||||
*/
|
||||
unregister(sourceId: string): this {
|
||||
this.sources.delete(sourceId)
|
||||
this.graph = null
|
||||
return this
|
||||
}
|
||||
|
||||
/**
|
||||
* Refreshes the feed by running all sources in dependency order.
|
||||
* Calls fetchContext() then fetchItems() on each source.
|
||||
*/
|
||||
async refresh(): Promise<FeedResult<TItems>> {
|
||||
const graph = this.ensureGraph()
|
||||
const errors: SourceError[] = []
|
||||
|
||||
// Reset context with fresh time
|
||||
let context: Context = { time: new Date() }
|
||||
|
||||
// Run fetchContext in topological order
|
||||
for (const source of graph.sorted) {
|
||||
if (source.fetchContext) {
|
||||
try {
|
||||
const update = await source.fetchContext(context)
|
||||
context = { ...context, ...update }
|
||||
} catch (err) {
|
||||
errors.push({
|
||||
sourceId: source.id,
|
||||
error: err instanceof Error ? err : new Error(String(err)),
|
||||
})
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Run fetchItems on all sources
|
||||
const items: FeedItem[] = []
|
||||
for (const source of graph.sorted) {
|
||||
if (source.fetchItems) {
|
||||
try {
|
||||
const sourceItems = await source.fetchItems(context)
|
||||
items.push(...sourceItems)
|
||||
} catch (err) {
|
||||
errors.push({
|
||||
sourceId: source.id,
|
||||
error: err instanceof Error ? err : new Error(String(err)),
|
||||
})
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Sort by priority descending
|
||||
items.sort((a, b) => b.priority - a.priority)
|
||||
|
||||
this.context = context
|
||||
|
||||
return { context, items: items as TItems[], errors }
|
||||
}
|
||||
|
||||
/**
|
||||
* Subscribes to feed updates. Returns unsubscribe function.
|
||||
*/
|
||||
subscribe(callback: FeedSubscriber<TItems>): () => void {
|
||||
this.subscribers.add(callback)
|
||||
return () => {
|
||||
this.subscribers.delete(callback)
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Starts reactive subscriptions on all sources.
|
||||
* Sources with onContextUpdate will trigger re-computation of dependents.
|
||||
*/
|
||||
start(): void {
|
||||
if (this.started) return
|
||||
|
||||
this.started = true
|
||||
const graph = this.ensureGraph()
|
||||
|
||||
for (const source of graph.sorted) {
|
||||
if (source.onContextUpdate) {
|
||||
const cleanup = source.onContextUpdate(
|
||||
(update) => {
|
||||
this.handleContextUpdate(source.id, update)
|
||||
},
|
||||
() => this.context,
|
||||
)
|
||||
this.cleanups.push(cleanup)
|
||||
}
|
||||
|
||||
if (source.onItemsUpdate) {
|
||||
const cleanup = source.onItemsUpdate(
|
||||
() => {
|
||||
this.scheduleRefresh()
|
||||
},
|
||||
() => this.context,
|
||||
)
|
||||
this.cleanups.push(cleanup)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Stops all reactive subscriptions.
|
||||
*/
|
||||
stop(): void {
|
||||
this.started = false
|
||||
for (const cleanup of this.cleanups) {
|
||||
cleanup()
|
||||
}
|
||||
this.cleanups = []
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns the current accumulated context.
|
||||
*/
|
||||
currentContext(): Context {
|
||||
return this.context
|
||||
}
|
||||
|
||||
private ensureGraph(): SourceGraph {
|
||||
if (!this.graph) {
|
||||
this.graph = buildGraph(Array.from(this.sources.values()))
|
||||
}
|
||||
return this.graph
|
||||
}
|
||||
|
||||
private handleContextUpdate(sourceId: string, update: Partial<Context>): void {
|
||||
this.context = { ...this.context, ...update, time: new Date() }
|
||||
|
||||
// Re-run dependents and notify
|
||||
this.refreshDependents(sourceId)
|
||||
}
|
||||
|
||||
private async refreshDependents(sourceId: string): Promise<void> {
|
||||
const graph = this.ensureGraph()
|
||||
const toRefresh = this.collectDependents(sourceId, graph)
|
||||
|
||||
// Re-run fetchContext for dependents in order
|
||||
for (const id of toRefresh) {
|
||||
const source = graph.sources.get(id)
|
||||
if (source?.fetchContext) {
|
||||
try {
|
||||
const update = await source.fetchContext(this.context)
|
||||
this.context = { ...this.context, ...update }
|
||||
} catch {
|
||||
// Errors during reactive updates are logged but don't stop propagation
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Collect items from all sources
|
||||
const items: FeedItem[] = []
|
||||
const errors: SourceError[] = []
|
||||
|
||||
for (const source of graph.sorted) {
|
||||
if (source.fetchItems) {
|
||||
try {
|
||||
const sourceItems = await source.fetchItems(this.context)
|
||||
items.push(...sourceItems)
|
||||
} catch (err) {
|
||||
errors.push({
|
||||
sourceId: source.id,
|
||||
error: err instanceof Error ? err : new Error(String(err)),
|
||||
})
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
items.sort((a, b) => b.priority - a.priority)
|
||||
|
||||
this.notifySubscribers({ context: this.context, items: items as TItems[], errors })
|
||||
}
|
||||
|
||||
private collectDependents(sourceId: string, graph: SourceGraph): string[] {
|
||||
const result: string[] = []
|
||||
const visited = new Set<string>()
|
||||
|
||||
const collect = (id: string): void => {
|
||||
const deps = graph.dependents.get(id) ?? []
|
||||
for (const dep of deps) {
|
||||
if (!visited.has(dep)) {
|
||||
visited.add(dep)
|
||||
result.push(dep)
|
||||
collect(dep)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
collect(sourceId)
|
||||
|
||||
// Return in topological order
|
||||
return graph.sorted.filter((s) => result.includes(s.id)).map((s) => s.id)
|
||||
}
|
||||
|
||||
private scheduleRefresh(): void {
|
||||
// Simple immediate refresh for now - could add debouncing later
|
||||
this.refresh().then((result) => {
|
||||
this.notifySubscribers(result)
|
||||
})
|
||||
}
|
||||
|
||||
private notifySubscribers(result: FeedResult<TItems>): void {
|
||||
this.subscribers.forEach((callback) => {
|
||||
try {
|
||||
callback(result)
|
||||
} catch {
|
||||
// Subscriber errors shouldn't break other subscribers
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
function buildGraph(sources: FeedSource[]): SourceGraph {
|
||||
const byId = new Map<string, FeedSource>()
|
||||
for (const source of sources) {
|
||||
byId.set(source.id, source)
|
||||
}
|
||||
|
||||
// Validate dependencies exist
|
||||
for (const source of sources) {
|
||||
for (const dep of source.dependencies ?? []) {
|
||||
if (!byId.has(dep)) {
|
||||
throw new Error(`Source "${source.id}" depends on "${dep}" which is not registered`)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Check for cycles and topologically sort
|
||||
const visited = new Set<string>()
|
||||
const visiting = new Set<string>()
|
||||
const sorted: FeedSource[] = []
|
||||
|
||||
function visit(id: string, path: string[]): void {
|
||||
if (visiting.has(id)) {
|
||||
const cycle = [...path.slice(path.indexOf(id)), id].join(" → ")
|
||||
throw new Error(`Circular dependency detected: ${cycle}`)
|
||||
}
|
||||
if (visited.has(id)) return
|
||||
|
||||
visiting.add(id)
|
||||
const source = byId.get(id)!
|
||||
for (const dep of source.dependencies ?? []) {
|
||||
visit(dep, [...path, id])
|
||||
}
|
||||
visiting.delete(id)
|
||||
visited.add(id)
|
||||
sorted.push(source)
|
||||
}
|
||||
|
||||
for (const source of sources) {
|
||||
visit(source.id, [])
|
||||
}
|
||||
|
||||
// Build reverse dependency map
|
||||
const dependents = new Map<string, string[]>()
|
||||
for (const source of sources) {
|
||||
for (const dep of source.dependencies ?? []) {
|
||||
const list = dependents.get(dep) ?? []
|
||||
list.push(source.id)
|
||||
dependents.set(dep, list)
|
||||
}
|
||||
}
|
||||
|
||||
return { sources: byId, sorted, dependents }
|
||||
}
|
||||
@@ -8,20 +8,35 @@ export type { FeedItem } from "./feed"
|
||||
// Feed Source
|
||||
export type { FeedSource } from "./feed-source"
|
||||
|
||||
// Feed Engine
|
||||
export type { FeedResult, FeedSubscriber, SourceError } from "./feed-engine"
|
||||
export { FeedEngine } from "./feed-engine"
|
||||
|
||||
// =============================================================================
|
||||
// DEPRECATED - Use FeedSource + FeedEngine instead
|
||||
// =============================================================================
|
||||
|
||||
// Data Source (deprecated - use FeedSource)
|
||||
export type { DataSource } from "./data-source"
|
||||
|
||||
// Context Provider
|
||||
// Context Provider (deprecated - use FeedSource)
|
||||
export type { ContextProvider } from "./context-provider"
|
||||
|
||||
// Context Bridge
|
||||
// Context Bridge (deprecated - use FeedEngine)
|
||||
export type { ProviderError, RefreshResult } from "./context-bridge"
|
||||
export { ContextBridge } from "./context-bridge"
|
||||
|
||||
// Reconciler
|
||||
export type { ReconcileResult, ReconcilerConfig, SourceError } from "./reconciler"
|
||||
// Reconciler (deprecated - use FeedEngine)
|
||||
export type {
|
||||
ReconcileResult,
|
||||
ReconcilerConfig,
|
||||
SourceError as ReconcilerSourceError,
|
||||
} from "./reconciler"
|
||||
export { Reconciler } from "./reconciler"
|
||||
|
||||
// Feed Controller
|
||||
export type { FeedControllerConfig, FeedSubscriber } from "./feed-controller"
|
||||
// Feed Controller (deprecated - use FeedEngine)
|
||||
export type {
|
||||
FeedControllerConfig,
|
||||
FeedSubscriber as FeedControllerSubscriber,
|
||||
} from "./feed-controller"
|
||||
export { FeedController } from "./feed-controller"
|
||||
|
||||
Reference in New Issue
Block a user