@agentick/gateway 0.0.1

package/src/__tests__/guards.spec.ts

@@ -0,0 +1,235 @@
+/**
+ * Guard Middleware Tests
+ *
+ * Tests for role-based and custom guard middleware behavior.
+ * Verifies GuardError is thrown with correct codes and type guards work.
+ */
+
+import { describe, it, expect, vi } from "vitest";
+import { Context, type KernelContext, type UserContext } from "@agentick/kernel";
+import { GuardError, isGuardError } from "@agentick/shared";
+
+// ============================================================================
+// Role guard behavior tests
+// ============================================================================
+
+describe("Role guard behavior", () => {
+  /**
+   * Simulates the role guard logic used in Gateway
+   */
+  function checkRoles(roles: string[], userRoles: string[]): boolean {
+    return roles.some((r) => userRoles.includes(r));
+  }
+
+  it("should pass when user has required role", () => {
+    expect(checkRoles(["admin"], ["admin", "user"])).toBe(true);
+  });
+
+  it("should pass when user has any of multiple required roles", () => {
+    expect(checkRoles(["admin", "moderator"], ["user", "moderator"])).toBe(true);
+  });
+
+  it("should fail when user lacks all required roles", () => {
+    expect(checkRoles(["admin", "moderator"], ["user"])).toBe(false);
+  });
+
+  it("should fail when user has no roles", () => {
+    expect(checkRoles(["admin"], [])).toBe(false);
+  });
+
+  it("should handle empty required roles (allows all)", () => {
+    expect(checkRoles([], ["user"])).toBe(false); // some() on empty returns false
+  });
+});
+
+// ============================================================================
+// Custom guard behavior tests
+// ============================================================================
+
+describe("Custom guard behavior", () => {
+  it("should allow when guard returns true", async () => {
+    const guard = (ctx: KernelContext) => true;
+
+    const user: UserContext = { id: "user-1" };
+    const ctx = Context.create({ user });
+
+    const result = await Context.run(ctx, () => guard(Context.get()));
+    expect(result).toBe(true);
+  });
+
+  it("should deny when guard returns false", async () => {
+    const guard = (ctx: KernelContext) => false;
+
+    const user: UserContext = { id: "user-1" };
+    const ctx = Context.create({ user });
+
+    const result = await Context.run(ctx, () => guard(Context.get()));
+    expect(result).toBe(false);
+  });
+
+  it("should support async guards", async () => {
+    const guard = async (ctx: KernelContext) => {
+      await new Promise((resolve) => setTimeout(resolve, 1));
+      return ctx.user?.id === "allowed-user";
+    };
+
+    const user1: UserContext = { id: "allowed-user" };
+    const ctx1 = Context.create({ user: user1 });
+    expect(await Context.run(ctx1, () => guard(Context.get()))).toBe(true);
+
+    const user2: UserContext = { id: "other-user" };
+    const ctx2 = Context.create({ user: user2 });
+    expect(await Context.run(ctx2, () => guard(Context.get()))).toBe(false);
+  });
+
+  it("should have access to user context", async () => {
+    const guard = (ctx: KernelContext) => {
+      return ctx.user?.id === "specific-user" && ctx.user?.roles?.includes("premium");
+    };
+
+    const premiumUser: UserContext = { id: "specific-user", roles: ["user", "premium"] };
+    const ctx1 = Context.create({ user: premiumUser });
+    expect(await Context.run(ctx1, () => guard(Context.get()))).toBe(true);
+
+    const regularUser: UserContext = { id: "specific-user", roles: ["user"] };
+    const ctx2 = Context.create({ user: regularUser });
+    expect(await Context.run(ctx2, () => guard(Context.get()))).toBe(false);
+  });
+
+  it("should have access to metadata", async () => {
+    const guard = (ctx: KernelContext) => {
+      return ctx.metadata?.tenantId === "allowed-tenant";
+    };
+
+    const ctx1 = Context.create({
+      user: { id: "1" },
+      metadata: { tenantId: "allowed-tenant" },
+    });
+    expect(await Context.run(ctx1, () => guard(Context.get()))).toBe(true);
+
+    const ctx2 = Context.create({
+      user: { id: "1" },
+      metadata: { tenantId: "other-tenant" },
+    });
+    expect(await Context.run(ctx2, () => guard(Context.get()))).toBe(false);
+  });
+});
+
+// ============================================================================
+// Combined guards behavior tests
+// ============================================================================
+
+describe("Combined guards behavior", () => {
+  it("should check roles before custom guard", async () => {
+    const roleCheck = vi.fn((roles: string[], userRoles: string[]) =>
+      roles.some((r) => userRoles.includes(r)),
+    );
+    const customGuard = vi.fn((ctx: KernelContext) => true);
+
+    async function checkAllGuards(
+      roles: string[],
+      guard: (ctx: KernelContext) => boolean,
+      ctx: KernelContext,
+    ): Promise<boolean> {
+      if (roles.length > 0) {
+        const userRoles = ctx.user?.roles ?? [];
+        if (!roleCheck(roles, userRoles)) {
+          return false;
+        }
+      }
+      return guard(ctx);
+    }
+
+    const user: UserContext = { id: "user-1", roles: ["user"] };
+    const ctx = Context.create({ user });
+
+    const result = await Context.run(ctx, () =>
+      checkAllGuards(["admin"], customGuard, Context.get()),
+    );
+
+    expect(result).toBe(false);
+    expect(roleCheck).toHaveBeenCalled();
+    expect(customGuard).not.toHaveBeenCalled();
+  });
+
+  it("should call custom guard after roles pass", async () => {
+    const customGuard = vi.fn((ctx: KernelContext) => ctx.user?.id === "allowed");
+
+    async function checkAllGuards(
+      roles: string[],
+      guard: (ctx: KernelContext) => boolean,
+      ctx: KernelContext,
+    ): Promise<boolean> {
+      if (roles.length > 0) {
+        const userRoles = ctx.user?.roles ?? [];
+        if (!roles.some((r) => userRoles.includes(r))) {
+          return false;
+        }
+      }
+      return guard(ctx);
+    }
+
+    const user: UserContext = { id: "allowed", roles: ["admin"] };
+    const ctx = Context.create({ user });
+
+    const result = await Context.run(ctx, () =>
+      checkAllGuards(["admin"], customGuard, Context.get()),
+    );
+
+    expect(result).toBe(true);
+    expect(customGuard).toHaveBeenCalled();
+  });
+});
+
+// ============================================================================
+// GuardError integration tests
+// ============================================================================
+
+describe("GuardError integration", () => {
+  it("GuardError has correct error code", () => {
+    const err = new GuardError("test");
+    expect(err.code).toBe("GUARD_DENIED");
+  });
+
+  it("GuardError.role() sets guardType", () => {
+    const err = GuardError.role(["admin"]);
+    expect(err.guardType).toBe("role");
+    expect(err.code).toBe("GUARD_DENIED");
+  });
+
+  it("GuardError.denied() sets guardType to custom", () => {
+    const err = GuardError.denied("Nope");
+    expect(err.guardType).toBe("custom");
+    expect(err.code).toBe("GUARD_DENIED");
+  });
+
+  it("isGuardError type guard works", () => {
+    expect(isGuardError(new GuardError("test"))).toBe(true);
+    expect(isGuardError(GuardError.role(["admin"]))).toBe(true);
+    expect(isGuardError(GuardError.denied("nope"))).toBe(true);
+    expect(isGuardError(new Error("Forbidden: something"))).toBe(false);
+    expect(isGuardError(null)).toBe(false);
+  });
+
+  it("GuardError propagates through guard middleware", () => {
+    const guard = (_ctx: KernelContext) => {
+      throw GuardError.role(["admin"]);
+    };
+
+    const ctx = Context.create({ user: { id: "1" } });
+
+    expect(() => Context.run(ctx, () => guard(Context.get()))).toThrow(GuardError);
+  });
+
+  it("should handle async guard throwing GuardError", async () => {
+    const guard = async (_ctx: KernelContext) => {
+      await new Promise((resolve) => setTimeout(resolve, 1));
+      throw GuardError.denied("Access denied");
+    };
+
+    const ctx = Context.create({ user: { id: "1" } });
+
+    await expect(Context.run(ctx, () => guard(Context.get()))).rejects.toThrow(GuardError);
+    await expect(Context.run(ctx, () => guard(Context.get()))).rejects.toThrow("Access denied");
+  });
+});

package/src/__tests__/protocol.spec.ts

@@ -0,0 +1,58 @@
+/**
+ * Protocol Tests
+ *
+ * Tests for session key parsing and formatting.
+ */
+
+import { describe, it, expect } from "vitest";
+import { parseSessionKey, formatSessionKey, type SessionKey } from "../transport-protocol.js";
+
+describe("parseSessionKey", () => {
+  it("parses simple session name with default agent", () => {
+    const result = parseSessionKey("main", "chat");
+    expect(result).toEqual({ appId: "chat", sessionName: "main" });
+  });
+
+  it("parses agent-prefixed session key", () => {
+    const result = parseSessionKey("research:task-123", "chat");
+    expect(result).toEqual({ appId: "research", sessionName: "task-123" });
+  });
+
+  it("preserves colons in session name after first", () => {
+    const result = parseSessionKey("slack:C012345:thread-xyz", "chat");
+    expect(result).toEqual({ appId: "slack", sessionName: "C012345:thread-xyz" });
+  });
+
+  it("handles phone numbers in session name", () => {
+    const result = parseSessionKey("whatsapp:+1234567890", "chat");
+    expect(result).toEqual({ appId: "whatsapp", sessionName: "+1234567890" });
+  });
+});
+
+describe("formatSessionKey", () => {
+  it("formats session key with agent prefix", () => {
+    const key: SessionKey = { appId: "chat", sessionName: "main" };
+    expect(formatSessionKey(key)).toBe("chat:main");
+  });
+
+  it("formats session key with complex session name", () => {
+    const key: SessionKey = { appId: "slack", sessionName: "C012345:thread-xyz" };
+    expect(formatSessionKey(key)).toBe("slack:C012345:thread-xyz");
+  });
+});
+
+describe("parseSessionKey and formatSessionKey roundtrip", () => {
+  it("roundtrips simple key", () => {
+    const original = "chat:main";
+    const parsed = parseSessionKey(original, "default");
+    const formatted = formatSessionKey(parsed);
+    expect(formatted).toBe(original);
+  });
+
+  it("roundtrips complex key", () => {
+    const original = "whatsapp:+1234567890";
+    const parsed = parseSessionKey(original, "default");
+    const formatted = formatSessionKey(parsed);
+    expect(formatted).toBe(original);
+  });
+});

package/src/__tests__/session-manager.spec.ts

@@ -0,0 +1,220 @@
+/**
+ * Session Manager Tests
+ */
+
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { SessionManager } from "../session-manager.js";
+import { AppRegistry } from "../app-registry.js";
+import type { App } from "@agentick/core";
+
+// Mock App for testing
+function createMockApp(name: string): App {
+  return {
+    session: vi.fn().mockReturnValue({
+      id: `session-${Date.now()}`,
+      close: vi.fn(),
+    }),
+    run: vi.fn() as any,
+    send: vi.fn() as any,
+    close: vi.fn(),
+    sessions: [],
+    has: vi.fn(),
+    isHibernated: vi.fn(),
+    hibernate: vi.fn(),
+    hibernatedSessions: vi.fn(),
+    onSessionCreate: vi.fn(),
+    onSessionClose: vi.fn(),
+  } as unknown as App;
+}
+
+describe("SessionManager", () => {
+  let registry: AppRegistry;
+  let manager: SessionManager;
+  let chatApp: App;
+  let researchApp: App;
+
+  beforeEach(() => {
+    chatApp = createMockApp("chat");
+    researchApp = createMockApp("research");
+    registry = new AppRegistry({ chat: chatApp, research: researchApp }, "chat");
+    manager = new SessionManager(registry);
+  });
+
+  describe("getOrCreate", () => {
+    it("creates new session with default app", async () => {
+      const session = await manager.getOrCreate("main");
+
+      expect(session.state.id).toBe("chat:main");
+      expect(session.state.appId).toBe("chat");
+      expect(session.appInfo.id).toBe("chat");
+      expect(session.coreSession).toBeNull();
+    });
+
+    it("creates new session with specified app", async () => {
+      const session = await manager.getOrCreate("research:task-1");
+
+      expect(session.state.id).toBe("research:task-1");
+      expect(session.state.appId).toBe("research");
+      expect(session.appInfo.id).toBe("research");
+    });
+
+    it("returns existing session", async () => {
+      const session1 = await manager.getOrCreate("main");
+      const session2 = await manager.getOrCreate("chat:main");
+
+      expect(session1).toBe(session2);
+    });
+
+    it("updates lastActivityAt on access", async () => {
+      const session1 = await manager.getOrCreate("main");
+      const firstActivity = session1.state.lastActivityAt;
+
+      // Small delay
+      await new Promise((r) => setTimeout(r, 10));
+
+      const session2 = await manager.getOrCreate("chat:main");
+      expect(session2.state.lastActivityAt.getTime()).toBeGreaterThan(firstActivity.getTime());
+    });
+  });
+
+  describe("get", () => {
+    it("returns existing session", async () => {
+      await manager.getOrCreate("main");
+      const session = manager.get("chat:main");
+
+      expect(session).toBeDefined();
+      expect(session?.state.id).toBe("chat:main");
+    });
+
+    it("returns undefined for non-existent session", () => {
+      expect(manager.get("nonexistent")).toBeUndefined();
+    });
+  });
+
+  describe("has", () => {
+    it("returns true for existing session", async () => {
+      await manager.getOrCreate("main");
+      expect(manager.has("chat:main")).toBe(true);
+    });
+
+    it("returns false for non-existent session", () => {
+      expect(manager.has("nonexistent")).toBe(false);
+    });
+  });
+
+  describe("close", () => {
+    it("removes session", async () => {
+      await manager.getOrCreate("main");
+      expect(manager.has("chat:main")).toBe(true);
+
+      await manager.close("chat:main");
+      expect(manager.has("chat:main")).toBe(false);
+    });
+
+    it("handles non-existent session gracefully", async () => {
+      await expect(manager.close("nonexistent")).resolves.toBeUndefined();
+    });
+  });
+
+  describe("reset", () => {
+    it("resets session state", async () => {
+      const session = await manager.getOrCreate("main");
+      session.state.messageCount = 10;
+
+      await manager.reset("chat:main");
+
+      expect(session.state.messageCount).toBe(0);
+    });
+
+    it("handles non-existent session gracefully", async () => {
+      await expect(manager.reset("nonexistent")).resolves.toBeUndefined();
+    });
+  });
+
+  describe("subscription management", () => {
+    it("adds subscriber to session", async () => {
+      await manager.getOrCreate("main");
+      await manager.subscribe("chat:main", "client-1");
+
+      const subscribers = manager.getSubscribers("chat:main");
+      expect(subscribers.has("client-1")).toBe(true);
+    });
+
+    it("removes subscriber from session", async () => {
+      await manager.getOrCreate("main");
+      await manager.subscribe("chat:main", "client-1");
+      manager.unsubscribe("chat:main", "client-1");
+
+      const subscribers = manager.getSubscribers("chat:main");
+      expect(subscribers.has("client-1")).toBe(false);
+    });
+
+    it("removes subscriber from all sessions", async () => {
+      await manager.getOrCreate("main");
+      await manager.getOrCreate("research:task-1");
+
+      await manager.subscribe("chat:main", "client-1");
+      await manager.subscribe("research:task-1", "client-1");
+
+      manager.unsubscribeAll("client-1");
+
+      expect(manager.getSubscribers("chat:main").has("client-1")).toBe(false);
+      expect(manager.getSubscribers("research:task-1").has("client-1")).toBe(false);
+    });
+
+    it("returns empty set for non-existent session", () => {
+      const subscribers = manager.getSubscribers("nonexistent");
+      expect(subscribers.size).toBe(0);
+    });
+  });
+
+  describe("message count", () => {
+    it("increments message count", async () => {
+      await manager.getOrCreate("main");
+      expect(manager.get("chat:main")?.state.messageCount).toBe(0);
+
+      manager.incrementMessageCount("chat:main");
+      expect(manager.get("chat:main")?.state.messageCount).toBe(1);
+
+      manager.incrementMessageCount("chat:main");
+      expect(manager.get("chat:main")?.state.messageCount).toBe(2);
+    });
+  });
+
+  describe("active state", () => {
+    it("sets active state", async () => {
+      await manager.getOrCreate("main");
+      expect(manager.get("chat:main")?.state.isActive).toBe(false);
+
+      manager.setActive("chat:main", true);
+      expect(manager.get("chat:main")?.state.isActive).toBe(true);
+
+      manager.setActive("chat:main", false);
+      expect(manager.get("chat:main")?.state.isActive).toBe(false);
+    });
+  });
+
+  describe("listing", () => {
+    it("returns all session ids", async () => {
+      await manager.getOrCreate("main");
+      await manager.getOrCreate("research:task-1");
+
+      const ids = manager.ids();
+      expect(ids).toHaveLength(2);
+      expect(ids).toContain("chat:main");
+      expect(ids).toContain("research:task-1");
+    });
+
+    it("returns sessions for specific app", async () => {
+      await manager.getOrCreate("main");
+      await manager.getOrCreate("chat:other");
+      await manager.getOrCreate("research:task-1");
+
+      const chatSessions = manager.forApp("chat");
+      expect(chatSessions).toHaveLength(2);
+
+      const researchSessions = manager.forApp("research");
+      expect(researchSessions).toHaveLength(1);
+    });
+  });
+});