@nkmc/gateway 0.1.0

package/test/registry/openapi-e2e.test.ts

@@ -0,0 +1,154 @@
+/**
+ * E2E integration test: OpenAPI → Registry → AgentFs → Real HTTP
+ *
+ * Uses JSONPlaceholder (https://jsonplaceholder.typicode.com) as a real, public REST API.
+ * These tests require network access and will be slower than unit tests.
+ */
+import { describe, it, expect, beforeAll } from "vitest";
+import { compileOpenApiSpec, fetchAndCompile } from "../../src/registry/openapi-compiler.js";
+import { MemoryRegistryStore } from "../../src/registry/memory-store.js";
+import { createRegistryResolver } from "../../src/registry/resolver.js";
+import { AgentFs } from "@nkmc/agent-fs";
+
+const DOMAIN = "jsonplaceholder.typicode.com";
+
+const JSONPLACEHOLDER_SPEC = {
+  openapi: "3.0.0",
+  info: {
+    title: "JSONPlaceholder",
+    version: "1.0.0",
+    description: "Free fake REST API for testing and prototyping.",
+  },
+  paths: {
+    "/posts": {
+      get: { summary: "List all posts", operationId: "listPosts" },
+      post: { summary: "Create a post", operationId: "createPost" },
+    },
+    "/posts/{id}": {
+      get: { summary: "Get post by ID", operationId: "getPost" },
+    },
+    "/users": {
+      get: { summary: "List all users", operationId: "listUsers" },
+    },
+    "/users/{id}": {
+      get: { summary: "Get user by ID", operationId: "getUser" },
+    },
+    "/comments": {
+      get: { summary: "List all comments", operationId: "listComments" },
+    },
+  },
+};
+
+describe("OpenAPI E2E: JSONPlaceholder (real network)", () => {
+  let fs: AgentFs;
+  let store: MemoryRegistryStore;
+
+  beforeAll(async () => {
+    // 1. Compile OpenAPI spec → ServiceRecord
+    const { record } = compileOpenApiSpec(JSONPLACEHOLDER_SPEC, {
+      domain: DOMAIN,
+    });
+
+    // 2. Register in store
+    store = new MemoryRegistryStore();
+    await store.put(DOMAIN, record);
+
+    // 3. Create AgentFs with registry resolver
+    const { onMiss, listDomains, searchDomains } = createRegistryResolver({
+      store,
+      wrapVirtualFiles: true,
+    });
+    fs = new AgentFs({ mounts: [], onMiss, listDomains, searchDomains });
+  });
+
+  it("ls / should list the registered service", async () => {
+    const result = await fs.execute("ls /");
+    expect(result.ok).toBe(true);
+    const entries = result.data as string[];
+    expect(entries).toContain(`${DOMAIN}/`);
+  });
+
+  it("ls /domain/ should list resources, _api, and virtual files", async () => {
+    const result = await fs.execute(`ls /${DOMAIN}/`);
+    expect(result.ok).toBe(true);
+    const entries = result.data as string[];
+    // Resources from Schema section
+    expect(entries).toContain("posts/");
+    expect(entries).toContain("users/");
+    expect(entries).toContain("comments/");
+    // API endpoints directory
+    expect(entries).toContain("_api/");
+    // Virtual files from VirtualFileBackend
+    expect(entries).toContain("_pricing.json");
+    expect(entries).toContain("_versions.json");
+  }, 10_000);
+
+  it("ls /domain/posts/ should list real posts from the API", async () => {
+    const result = await fs.execute(`ls /${DOMAIN}/posts/`);
+    expect(result.ok).toBe(true);
+    const entries = result.data as string[];
+    // JSONPlaceholder has 100 posts
+    expect(entries.length).toBe(100);
+    expect(entries).toContain("1.json");
+    expect(entries).toContain("100.json");
+  }, 15_000);
+
+  it("cat /domain/posts/1 should return real post data", async () => {
+    const result = await fs.execute(`cat /${DOMAIN}/posts/1`);
+    expect(result.ok).toBe(true);
+    const post = result.data as any;
+    expect(post.id).toBe(1);
+    expect(post.userId).toBe(1);
+    expect(post.title).toBeTruthy();
+    expect(post.body).toBeTruthy();
+  }, 10_000);
+
+  it("cat /domain/users/1 should return real user data", async () => {
+    const result = await fs.execute(`cat /${DOMAIN}/users/1`);
+    expect(result.ok).toBe(true);
+    const user = result.data as any;
+    expect(user.id).toBe(1);
+    expect(user.name).toBeTruthy();
+    expect(user.email).toBeTruthy();
+  }, 10_000);
+
+  it("ls /domain/_api/ should list all endpoints", async () => {
+    const result = await fs.execute(`ls /${DOMAIN}/_api/`);
+    expect(result.ok).toBe(true);
+    const entries = result.data as string[];
+    expect(entries.length).toBe(6);
+    expect(entries.some((e) => e.includes("list-all-posts"))).toBe(true);
+    expect(entries.some((e) => e.includes("list-all-users"))).toBe(true);
+  }, 10_000);
+
+  it("cat /domain/_pricing.json should return pricing info", async () => {
+    const result = await fs.execute(`cat /${DOMAIN}/_pricing.json`);
+    expect(result.ok).toBe(true);
+  });
+
+  it("cat /domain/_versions.json should return version info", async () => {
+    const result = await fs.execute(`cat /${DOMAIN}/_versions.json`);
+    expect(result.ok).toBe(true);
+    const data = result.data as any;
+    expect(data.domain).toBe(DOMAIN);
+    expect(data.versions).toHaveLength(1);
+    expect(data.versions[0].version).toBe("1.0.0");
+  });
+});
+
+describe("fetchAndCompile with real Petstore spec", () => {
+  it("should fetch and compile the Petstore OpenAPI spec", async () => {
+    const result = await fetchAndCompile(
+      "https://petstore3.swagger.io/api/v3/openapi.json",
+      { domain: "petstore3.swagger.io" },
+    );
+
+    expect(result.record.name).toBeTruthy();
+    expect(result.record.endpoints.length).toBeGreaterThan(0);
+    expect(result.resources.length).toBeGreaterThan(0);
+    expect(result.record.source?.type).toBe("openapi");
+    expect(result.record.source?.url).toBe("https://petstore3.swagger.io/api/v3/openapi.json");
+    expect(result.skillMd).toContain("## Schema");
+    expect(result.skillMd).toContain("## API");
+  }, 15_000);
+});

package/test/registry/passthrough-e2e.test.ts

@@ -0,0 +1,109 @@
+/**
+ * E2E integration test: HTTP Passthrough mode with real API.
+ *
+ * Registers a service with a bare skill.md (no Schema, no API sections),
+ * causing HttpBackend to enter passthrough mode where all paths proxy
+ * directly to the target API without resource/endpoint mapping.
+ *
+ * Uses JSONPlaceholder as the real API target.
+ */
+import { describe, it, expect, beforeAll } from "vitest";
+import { parseSkillMd } from "../../src/registry/skill-parser.js";
+import { MemoryRegistryStore } from "../../src/registry/memory-store.js";
+import { createRegistryResolver } from "../../src/registry/resolver.js";
+import { AgentFs } from "@nkmc/agent-fs";
+
+const DOMAIN = "jsonplaceholder.typicode.com";
+
+// Bare skill.md — no ## Schema, no ## API
+// skillToHttpConfig will produce resources=[], endpoints=[] → passthrough mode
+const BARE_SKILL_MD = `---
+name: "JSONPlaceholder"
+gateway: nkmc
+version: "1.0"
+roles: [agent]
+---
+
+# JSONPlaceholder
+
+Free fake REST API for testing. All paths proxy directly to the target.
+`;
+
+describe("HTTP Passthrough E2E: JSONPlaceholder (real network)", () => {
+  let fs: AgentFs;
+
+  beforeAll(async () => {
+    const store = new MemoryRegistryStore();
+    const record = parseSkillMd(DOMAIN, BARE_SKILL_MD);
+    await store.put(DOMAIN, record);
+
+    const { onMiss, listDomains, searchDomains } = createRegistryResolver({
+      store,
+      wrapVirtualFiles: true,
+    });
+    fs = new AgentFs({ mounts: [], onMiss, listDomains, searchDomains });
+  });
+
+  it("ls / should list the registered service", async () => {
+    const result = await fs.execute("ls /");
+    expect(result.ok).toBe(true);
+    expect(result.data).toContain(`${DOMAIN}/`);
+  });
+
+  it("ls /domain/ should show only virtual files (no resources in passthrough)", async () => {
+    const result = await fs.execute(`ls /${DOMAIN}/`);
+    expect(result.ok).toBe(true);
+    const entries = result.data as string[];
+    // Passthrough root = empty from HttpBackend + virtual files from wrapper
+    expect(entries).toContain("_pricing.json");
+    expect(entries).toContain("_versions.json");
+    // No resource directories — passthrough doesn't know them
+    expect(entries).not.toContain("posts/");
+  });
+
+  it("ls /domain/posts should list real posts via direct proxy", async () => {
+    const result = await fs.execute(`ls /${DOMAIN}/posts`);
+    expect(result.ok).toBe(true);
+    const entries = result.data as string[];
+    // JSONPlaceholder has 100 posts, passthrough maps item.id to string
+    expect(entries.length).toBe(100);
+    expect(entries).toContain("1");
+  }, 15_000);
+
+  it("cat /domain/posts/1 should proxy GET and return real post", async () => {
+    const result = await fs.execute(`cat /${DOMAIN}/posts/1`);
+    expect(result.ok).toBe(true);
+    const post = result.data as any;
+    expect(post.id).toBe(1);
+    expect(post.userId).toBe(1);
+    expect(post.title).toBeTruthy();
+    expect(post.body).toBeTruthy();
+  }, 10_000);
+
+  it("cat /domain/users/3 should proxy GET and return real user", async () => {
+    const result = await fs.execute(`cat /${DOMAIN}/users/3`);
+    expect(result.ok).toBe(true);
+    const user = result.data as any;
+    expect(user.id).toBe(3);
+    expect(user.name).toBeTruthy();
+    expect(user.email).toBeTruthy();
+  }, 10_000);
+
+  it("cat /domain/posts/1/comments should proxy nested path", async () => {
+    const result = await fs.execute(`cat /${DOMAIN}/posts/1/comments`);
+    expect(result.ok).toBe(true);
+    const comments = result.data as any[];
+    expect(Array.isArray(comments)).toBe(true);
+    expect(comments.length).toBeGreaterThan(0);
+    expect(comments[0].postId).toBe(1);
+  }, 10_000);
+
+  it("grep on /domain/posts should proxy search with ?q=", async () => {
+    const result = await fs.execute(`grep "test" /${DOMAIN}/posts`);
+    expect(result.ok).toBe(true);
+    // JSONPlaceholder doesn't actually filter by ?q=, it returns all posts
+    // But the proxy mechanism should work without error
+    const data = result.data as any[];
+    expect(Array.isArray(data)).toBe(true);
+  }, 10_000);
+});

package/test/registry/resolver-peer.test.ts

@@ -0,0 +1,299 @@
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { MemoryRegistryStore } from "../../src/registry/memory-store.js";
+import { parseSkillMd } from "../../src/registry/skill-parser.js";
+import { createRegistryResolver } from "../../src/registry/resolver.js";
+import type { PeerGateway } from "../../src/federation/types.js";
+import type { PeerClient, PeerQueryResult } from "../../src/federation/peer-client.js";
+import { PeerBackend } from "../../src/federation/peer-backend.js";
+import type { HttpAuth } from "@nkmc/agent-fs";
+
+const ACME_SKILL = `---
+name: "Acme Store"
+gateway: nkmc
+version: "1.0"
+roles: [agent]
+---
+
+# Acme Store
+
+E-commerce store.
+
+## API
+
+### List products
+
+\`GET /api/products\` — free, public
+`;
+
+function makePeer(overrides: Partial<PeerGateway> = {}): PeerGateway {
+  return {
+    id: "peer-1",
+    name: "Peer Gateway 1",
+    url: "https://peer1.example.com",
+    sharedSecret: "secret-1",
+    status: "active",
+    advertisedDomains: [],
+    lastSeen: Date.now(),
+    createdAt: Date.now(),
+    ...overrides,
+  };
+}
+
+function makeMockPeerClient(
+  queryFn: (peer: PeerGateway, domain: string) => Promise<PeerQueryResult>,
+): PeerClient {
+  return {
+    selfId: "self-gateway",
+    query: queryFn,
+    exec: vi.fn(),
+    announce: vi.fn(),
+  } as unknown as PeerClient;
+}
+
+function makeMockPeerStore(peers: PeerGateway[]) {
+  return {
+    listPeers: vi.fn(async () => peers),
+  };
+}
+
+function makeMockVault(entries: Record<string, HttpAuth>) {
+  return {
+    get: vi.fn(async (domain: string) => {
+      const auth = entries[domain];
+      return auth ? { auth } : null;
+    }),
+  };
+}
+
+describe("Resolver peer fallback", () => {
+  let store: MemoryRegistryStore;
+
+  beforeEach(async () => {
+    store = new MemoryRegistryStore();
+    const record = parseSkillMd("acme-store.com", ACME_SKILL);
+    await store.put("acme-store.com", record);
+  });
+
+  it("local credential exists → uses local HttpBackend (no peer query)", async () => {
+    const peer = makePeer();
+    const peerClient = makeMockPeerClient(async () => ({ available: true }));
+    const peerStore = makeMockPeerStore([peer]);
+    const vault = makeMockVault({
+      "acme-store.com": { type: "bearer", token: "local-token" },
+    });
+
+    const { onMiss } = createRegistryResolver({
+      store,
+      vault,
+      peerStore,
+      peerClient,
+      wrapVirtualFiles: false,
+    });
+
+    let mountedPath: string | undefined;
+    const result = await onMiss("/acme-store.com/products", (mount) => {
+      mountedPath = mount.path;
+    });
+
+    expect(result).toBe(true);
+    expect(mountedPath).toBe("/acme-store.com");
+    // Peer should NOT have been queried since local credential was found
+    expect(peerStore.listPeers).not.toHaveBeenCalled();
+  });
+
+  it("no local credential, peer has domain → mounts PeerBackend", async () => {
+    const peer = makePeer();
+    const peerClient = makeMockPeerClient(async () => ({ available: true }));
+    const peerStore = makeMockPeerStore([peer]);
+    // No vault → no local credentials
+    const { onMiss } = createRegistryResolver({
+      store,
+      peerStore,
+      peerClient,
+      wrapVirtualFiles: false,
+    });
+
+    let mountedBackend: unknown;
+    let mountedPath: string | undefined;
+    const result = await onMiss("/acme-store.com/products", (mount) => {
+      mountedBackend = mount.backend;
+      mountedPath = mount.path;
+    });
+
+    expect(result).toBe(true);
+    expect(mountedPath).toBe("/acme-store.com");
+    expect(mountedBackend).toBeInstanceOf(PeerBackend);
+  });
+
+  it("no local credential, no peer has domain → returns false", async () => {
+    const peer = makePeer();
+    const peerClient = makeMockPeerClient(async () => ({ available: false }));
+    const peerStore = makeMockPeerStore([peer]);
+
+    const { onMiss } = createRegistryResolver({
+      store,
+      peerStore,
+      peerClient,
+      wrapVirtualFiles: false,
+    });
+
+    // Note: with no vault and peer returning unavailable, the resolver
+    // still falls through to mount a local HttpBackend (no auth).
+    // The peer fallback returns false, but the local path continues.
+    const result = await onMiss("/acme-store.com/products", () => {});
+    // Local record exists, so it mounts the local backend (without auth)
+    expect(result).toBe(true);
+  });
+
+  it("peer with non-matching advertised domains → skips that peer", async () => {
+    const peer = makePeer({
+      advertisedDomains: ["other-api.com", "another-api.com"],
+    });
+    const queryFn = vi.fn(async () => ({ available: true }));
+    const peerClient = makeMockPeerClient(queryFn);
+    const peerStore = makeMockPeerStore([peer]);
+
+    const { onMiss } = createRegistryResolver({
+      store,
+      peerStore,
+      peerClient,
+      wrapVirtualFiles: false,
+    });
+
+    let mountedBackend: unknown;
+    await onMiss("/acme-store.com/products", (mount) => {
+      mountedBackend = mount.backend;
+    });
+
+    // Peer's advertised domains don't include acme-store.com, so query was never called
+    expect(queryFn).not.toHaveBeenCalled();
+    // Falls through to local mount (no credential, but still mounts local backend)
+    expect(mountedBackend).not.toBeInstanceOf(PeerBackend);
+  });
+
+  it("no local record at all, but peer has domain → mounts PeerBackend", async () => {
+    const peer = makePeer();
+    const peerClient = makeMockPeerClient(async () => ({ available: true }));
+    const peerStore = makeMockPeerStore([peer]);
+
+    const { onMiss } = createRegistryResolver({
+      store,
+      peerStore,
+      peerClient,
+      wrapVirtualFiles: false,
+    });
+
+    // "unknown-api.com" is NOT in the local store
+    let mountedBackend: unknown;
+    let mountedPath: string | undefined;
+    const result = await onMiss("/unknown-api.com/data", (mount) => {
+      mountedBackend = mount.backend;
+      mountedPath = mount.path;
+    });
+
+    expect(result).toBe(true);
+    expect(mountedPath).toBe("/unknown-api.com");
+    expect(mountedBackend).toBeInstanceOf(PeerBackend);
+  });
+
+  it("no local record, no peerClient configured → returns false", async () => {
+    const { onMiss } = createRegistryResolver({
+      store,
+      wrapVirtualFiles: false,
+    });
+
+    const result = await onMiss("/unknown-api.com/data", () => {});
+    expect(result).toBe(false);
+  });
+
+  it("no local record, peer does not have domain → returns false", async () => {
+    const peer = makePeer();
+    const peerClient = makeMockPeerClient(async () => ({ available: false }));
+    const peerStore = makeMockPeerStore([peer]);
+
+    const { onMiss } = createRegistryResolver({
+      store,
+      peerStore,
+      peerClient,
+      wrapVirtualFiles: false,
+    });
+
+    const result = await onMiss("/unknown-api.com/data", () => {});
+    expect(result).toBe(false);
+  });
+
+  it("peer fallback with versioned path → mounts at versioned path", async () => {
+    const peer = makePeer();
+    const peerClient = makeMockPeerClient(async () => ({ available: true }));
+    const peerStore = makeMockPeerStore([peer]);
+
+    const { onMiss } = createRegistryResolver({
+      store,
+      peerStore,
+      peerClient,
+      wrapVirtualFiles: false,
+    });
+
+    let mountedPath: string | undefined;
+    const result = await onMiss("/unknown-api.com@v2/data", (mount) => {
+      mountedPath = mount.path;
+    });
+
+    expect(result).toBe(true);
+    expect(mountedPath).toBe("/unknown-api.com@v2");
+  });
+
+  it("peer fallback uses agent id when available", async () => {
+    const peer = makePeer();
+    let capturedPeerBackend: PeerBackend | undefined;
+    const peerClient = makeMockPeerClient(async () => ({ available: true }));
+    const peerStore = makeMockPeerStore([peer]);
+
+    const { onMiss } = createRegistryResolver({
+      store,
+      peerStore,
+      peerClient,
+      wrapVirtualFiles: false,
+    });
+
+    const agent = { id: "agent-42", roles: ["user"] };
+    await onMiss(
+      "/unknown-api.com/data",
+      (mount) => {
+        capturedPeerBackend = mount.backend as PeerBackend;
+      },
+      agent,
+    );
+
+    expect(capturedPeerBackend).toBeInstanceOf(PeerBackend);
+  });
+
+  it("selects first available peer when multiple peers exist", async () => {
+    const peer1 = makePeer({ id: "peer-1", url: "https://peer1.example.com" });
+    const peer2 = makePeer({ id: "peer-2", url: "https://peer2.example.com" });
+
+    const queryFn = vi.fn(async (peer: PeerGateway) => {
+      if (peer.id === "peer-1") return { available: false };
+      return { available: true };
+    });
+    const peerClient = makeMockPeerClient(queryFn);
+    const peerStore = makeMockPeerStore([peer1, peer2]);
+
+    const { onMiss } = createRegistryResolver({
+      store,
+      peerStore,
+      peerClient,
+      wrapVirtualFiles: false,
+    });
+
+    let mountedBackend: unknown;
+    const result = await onMiss("/unknown-api.com/data", (mount) => {
+      mountedBackend = mount.backend;
+    });
+
+    expect(result).toBe(true);
+    expect(mountedBackend).toBeInstanceOf(PeerBackend);
+    // Both peers were queried since first returned unavailable
+    expect(queryFn).toHaveBeenCalledTimes(2);
+  });
+});