feat: runtime provider hotswap (#82)

Add ability to replace a FeedSourceProvider at runtime and propagate
the new source to all active (and pending) user sessions, invalidating
their feed caches.

Co-authored-by: Ona <no-reply@ona.com>

apps/aelis-backend/src/session/user-session.test.ts

@@ -214,3 +214,175 @@ describe("UserSession.feed", () => {
 		expect(result.items[0]!.data.value).toBe(42)
 	})
 })
+
+describe("UserSession.replaceSource", () => {
+	test("replaces source and invalidates feed cache", async () => {
+		const itemsA: FeedItem[] = [
+			{
+				id: "a-1",
+				sourceId: "test",
+				type: "test",
+				timestamp: new Date("2025-01-01T00:00:00.000Z"),
+				data: { from: "a" },
+			},
+		]
+		const itemsB: FeedItem[] = [
+			{
+				id: "b-1",
+				sourceId: "test",
+				type: "test",
+				timestamp: new Date("2025-01-01T00:00:00.000Z"),
+				data: { from: "b" },
+			},
+		]
+
+		const sourceA = createStubSource("test", itemsA)
+		const session = new UserSession([sourceA])
+
+		const result1 = await session.feed()
+		expect(result1.items).toHaveLength(1)
+		expect(result1.items[0]!.data.from).toBe("a")
+
+		const sourceB = createStubSource("test", itemsB)
+		session.replaceSource("test", sourceB)
+
+		const result2 = await session.feed()
+		expect(result2.items).toHaveLength(1)
+		expect(result2.items[0]!.data.from).toBe("b")
+	})
+
+	test("getSource returns new source after replace", () => {
+		const sourceA = createStubSource("test")
+		const session = new UserSession([sourceA])
+
+		const sourceB = createStubSource("test")
+		session.replaceSource("test", sourceB)
+
+		expect(session.getSource("test")).toBe(sourceB)
+		expect(session.getSource("test")).not.toBe(sourceA)
+	})
+
+	test("throws when replacing a source that is not registered", () => {
+		const session = new UserSession([createStubSource("test")])
+
+		expect(() => session.replaceSource("nonexistent", createStubSource("other"))).toThrow(
+			'Cannot replace source "nonexistent": not registered',
+		)
+	})
+
+	test("other sources are unaffected by replace", async () => {
+		const sourceA = createStubSource("source-a", [
+			{
+				id: "a-1",
+				sourceId: "source-a",
+				type: "test",
+				timestamp: new Date(),
+				data: { from: "a" },
+			},
+		])
+		const sourceB = createStubSource("source-b", [
+			{
+				id: "b-1",
+				sourceId: "source-b",
+				type: "test",
+				timestamp: new Date(),
+				data: { from: "b" },
+			},
+		])
+		const session = new UserSession([sourceA, sourceB])
+
+		const replacement = createStubSource("source-a", [
+			{
+				id: "a-2",
+				sourceId: "source-a",
+				type: "test",
+				timestamp: new Date(),
+				data: { from: "a-new" },
+			},
+		])
+		session.replaceSource("source-a", replacement)
+
+		const result = await session.feed()
+		expect(result.items).toHaveLength(2)
+
+		const ids = result.items.map((i) => i.id).sort()
+		expect(ids).toEqual(["a-2", "b-1"])
+	})
+
+	test("invalidates enhancement cache on replace", async () => {
+		const items: FeedItem[] = [
+			{
+				id: "item-1",
+				sourceId: "test",
+				type: "test",
+				timestamp: new Date(),
+				data: { version: 1 },
+			},
+		]
+		let enhanceCount = 0
+		const enhancer = async (feedItems: FeedItem[]) => {
+			enhanceCount++
+			return feedItems.map((item) => ({ ...item, data: { ...item.data, enhanced: true } }))
+		}
+
+		const session = new UserSession([createStubSource("test", items)], enhancer)
+
+		await session.feed()
+		expect(enhanceCount).toBe(1)
+
+		const newItems: FeedItem[] = [
+			{
+				id: "item-2",
+				sourceId: "test",
+				type: "test",
+				timestamp: new Date(),
+				data: { version: 2 },
+			},
+		]
+		session.replaceSource("test", createStubSource("test", newItems))
+
+		const result = await session.feed()
+		expect(enhanceCount).toBe(2)
+		expect(result.items[0]!.id).toBe("item-2")
+		expect(result.items[0]!.data.enhanced).toBe(true)
+	})
+})
+
+describe("UserSession.removeSource", () => {
+	test("removes source from engine and sources map", () => {
+		const session = new UserSession([createStubSource("test-a"), createStubSource("test-b")])
+
+		session.removeSource("test-a")
+
+		expect(session.getSource("test-a")).toBeUndefined()
+		expect(session.getSource("test-b")).toBeDefined()
+	})
+
+	test("invalidates feed cache on remove", async () => {
+		const items: FeedItem[] = [
+			{
+				id: "item-1",
+				sourceId: "test",
+				type: "test",
+				timestamp: new Date(),
+				data: {},
+			},
+		]
+		const session = new UserSession([createStubSource("test", items)])
+
+		const result1 = await session.feed()
+		expect(result1.items).toHaveLength(1)
+
+		session.removeSource("test")
+
+		const result2 = await session.feed()
+		expect(result2.items).toHaveLength(0)
+	})
+
+	test("is a no-op for unknown source", () => {
+		const session = new UserSession([createStubSource("test")])
+
+		expect(() => session.removeSource("unknown")).not.toThrow()
+		expect(session.getSource("test")).toBeDefined()
+	})
+})