@fatagnus/remote-cmd-relay-convex 1.0.0

package/src/commands.test.ts

@@ -0,0 +1,331 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import {
+  createRelayTestConvex,
+  createTestRelayAssignment,
+  createTestCommand,
+  type RelayTestConvex,
+} from "./test.setup";
+import { api } from "./_generated/api";
+
+describe("command queue", () => {
+  let t: RelayTestConvex;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    t = createRelayTestConvex();
+  });
+
+  afterEach(async () => {
+    await t.finishAllScheduledFunctions(vi.runAllTimers);
+    vi.useRealTimers();
+  });
+
+  describe("queue", () => {
+    it("queues a local command", async () => {
+      const result = await t.mutation(api.commands.queue, {
+        machineId: "machine-1",
+        command: "echo hello",
+        targetType: "local",
+        createdBy: "user-1",
+      });
+
+      expect(result).toBeDefined();
+
+      const cmd = await t.run(async (ctx) => {
+        return await ctx.db.get(result);
+      });
+
+      expect(cmd?.machineId).toBe("machine-1");
+      expect(cmd?.command).toBe("echo hello");
+      expect(cmd?.targetType).toBe("local");
+      expect(cmd?.status).toBe("pending");
+      expect(cmd?.timeoutMs).toBe(30000); // default
+    });
+
+    it("queues an SSH command with target details", async () => {
+      const result = await t.mutation(api.commands.queue, {
+        machineId: "machine-1",
+        command: "uptime",
+        targetType: "ssh",
+        targetHost: "192.168.1.100",
+        targetPort: 2222,
+        targetUsername: "admin",
+        timeoutMs: 60000,
+        createdBy: "user-1",
+      });
+
+      const cmd = await t.run(async (ctx) => {
+        return await ctx.db.get(result);
+      });
+
+      expect(cmd?.targetType).toBe("ssh");
+      expect(cmd?.targetHost).toBe("192.168.1.100");
+      expect(cmd?.targetPort).toBe(2222);
+      expect(cmd?.targetUsername).toBe("admin");
+      expect(cmd?.timeoutMs).toBe(60000);
+    });
+
+    it("requires targetHost and targetUsername for SSH commands", async () => {
+      await expect(
+        t.mutation(api.commands.queue, {
+          machineId: "machine-1",
+          command: "uptime",
+          targetType: "ssh",
+          createdBy: "user-1",
+        })
+      ).rejects.toThrow("SSH target requires targetHost and targetUsername");
+    });
+  });
+
+  describe("listPending", () => {
+    it("lists pending commands for a machine", async () => {
+      await createTestCommand(t, {
+        machineId: "machine-1",
+        command: "echo 1",
+        status: "pending",
+      });
+      await createTestCommand(t, {
+        machineId: "machine-1",
+        command: "echo 2",
+        status: "pending",
+      });
+      await createTestCommand(t, {
+        machineId: "machine-1",
+        command: "echo completed",
+        status: "completed",
+      });
+      await createTestCommand(t, {
+        machineId: "machine-2",
+        command: "echo other",
+        status: "pending",
+      });
+
+      const result = await t.query(api.commands.listPending, {
+        machineId: "machine-1",
+      });
+
+      expect(result).toHaveLength(2);
+      expect(result.every((c) => c.status === "pending")).toBe(true);
+      expect(result.every((c) => c.machineId === "machine-1")).toBe(true);
+    });
+
+    it("respects limit parameter", async () => {
+      for (let i = 0; i < 5; i++) {
+        await createTestCommand(t, {
+          machineId: "machine-1",
+          command: `echo ${i}`,
+          status: "pending",
+        });
+      }
+
+      const result = await t.query(api.commands.listPending, {
+        machineId: "machine-1",
+        limit: 2,
+      });
+
+      expect(result).toHaveLength(2);
+    });
+  });
+
+  describe("get", () => {
+    it("returns command by ID", async () => {
+      const created = await createTestCommand(t, {
+        machineId: "machine-1",
+        command: "test command",
+      });
+
+      const result = await t.query(api.commands.get, {
+        id: created._id,
+      });
+
+      expect(result).not.toBeNull();
+      expect(result?.command).toBe("test command");
+      expect(result?.machineId).toBe("machine-1");
+    });
+
+    it("returns null for non-existent command", async () => {
+      const created = await createTestCommand(t, { machineId: "m" });
+      await t.run(async (ctx) => {
+        await ctx.db.delete(created._id);
+      });
+
+      const result = await t.query(api.commands.get, {
+        id: created._id,
+      });
+
+      expect(result).toBeNull();
+    });
+  });
+
+  describe("claim", () => {
+    it("claims a pending command", async () => {
+      const created = await createTestCommand(t, {
+        machineId: "machine-1",
+        status: "pending",
+      });
+
+      const result = await t.mutation(api.commands.claim, {
+        id: created._id,
+        claimedBy: "relay-1",
+      });
+
+      expect(result).toBe(true);
+
+      const cmd = await t.run(async (ctx) => {
+        return await ctx.db.get(created._id);
+      });
+
+      expect(cmd?.status).toBe("claimed");
+      expect(cmd?.claimedBy).toBe("relay-1");
+      expect(cmd?.claimedAt).toBeDefined();
+    });
+
+    it("prevents double claiming", async () => {
+      const created = await createTestCommand(t, {
+        machineId: "machine-1",
+        status: "pending",
+      });
+
+      // First claim succeeds
+      const result1 = await t.mutation(api.commands.claim, {
+        id: created._id,
+        claimedBy: "relay-1",
+      });
+      expect(result1).toBe(true);
+
+      // Second claim fails
+      const result2 = await t.mutation(api.commands.claim, {
+        id: created._id,
+        claimedBy: "relay-2",
+      });
+      expect(result2).toBe(false);
+    });
+
+    it("throws for non-existent command", async () => {
+      const created = await createTestCommand(t, { machineId: "m" });
+      await t.run(async (ctx) => {
+        await ctx.db.delete(created._id);
+      });
+
+      await expect(
+        t.mutation(api.commands.claim, {
+          id: created._id,
+          claimedBy: "relay-1",
+        })
+      ).rejects.toThrow("Command not found");
+    });
+  });
+
+  describe("startExecution", () => {
+    it("updates status to executing", async () => {
+      const created = await createTestCommand(t, {
+        machineId: "machine-1",
+        status: "claimed",
+      });
+
+      await t.mutation(api.commands.startExecution, {
+        id: created._id,
+      });
+
+      const cmd = await t.run(async (ctx) => {
+        return await ctx.db.get(created._id);
+      });
+
+      expect(cmd?.status).toBe("executing");
+    });
+  });
+
+  describe("complete", () => {
+    it("completes command with success", async () => {
+      const created = await createTestCommand(t, {
+        machineId: "machine-1",
+        status: "executing",
+      });
+
+      await t.mutation(api.commands.complete, {
+        id: created._id,
+        success: true,
+        output: "Hello, World!",
+        exitCode: 0,
+        durationMs: 150,
+      });
+
+      const cmd = await t.run(async (ctx) => {
+        return await ctx.db.get(created._id);
+      });
+
+      expect(cmd?.status).toBe("completed");
+      expect(cmd?.output).toBe("Hello, World!");
+      expect(cmd?.exitCode).toBe(0);
+      expect(cmd?.durationMs).toBe(150);
+      expect(cmd?.completedAt).toBeDefined();
+    });
+
+    it("completes command with failure", async () => {
+      const created = await createTestCommand(t, {
+        machineId: "machine-1",
+        status: "executing",
+      });
+
+      await t.mutation(api.commands.complete, {
+        id: created._id,
+        success: false,
+        stderr: "Command failed",
+        exitCode: 1,
+        error: "Non-zero exit code",
+        durationMs: 50,
+      });
+
+      const cmd = await t.run(async (ctx) => {
+        return await ctx.db.get(created._id);
+      });
+
+      expect(cmd?.status).toBe("failed");
+      expect(cmd?.stderr).toBe("Command failed");
+      expect(cmd?.exitCode).toBe(1);
+      expect(cmd?.error).toBe("Non-zero exit code");
+    });
+  });
+
+  describe("listRecent", () => {
+    it("lists recent commands for a machine", async () => {
+      await createTestCommand(t, {
+        machineId: "machine-1",
+        command: "echo 1",
+        status: "completed",
+      });
+      await createTestCommand(t, {
+        machineId: "machine-1",
+        command: "echo 2",
+        status: "failed",
+      });
+      await createTestCommand(t, {
+        machineId: "machine-1",
+        command: "echo 3",
+        status: "pending",
+      });
+
+      const result = await t.query(api.commands.listRecent, {
+        machineId: "machine-1",
+      });
+
+      expect(result).toHaveLength(3);
+    });
+
+    it("respects limit parameter", async () => {
+      for (let i = 0; i < 10; i++) {
+        await createTestCommand(t, {
+          machineId: "machine-1",
+          command: `echo ${i}`,
+        });
+      }
+
+      const result = await t.query(api.commands.listRecent, {
+        machineId: "machine-1",
+        limit: 5,
+      });
+
+      expect(result).toHaveLength(5);
+    });
+  });
+});

package/src/commands.ts

@@ -0,0 +1,286 @@
+import { v } from "convex/values";
+import { mutation, query } from "./_generated/server";
+import { commandStatusValidator, targetTypeValidator } from "./schema";
+
+/**
+ * Queue a new command for execution
+ */
+export const queue = mutation({
+  args: {
+    machineId: v.string(),
+    command: v.string(),
+    targetType: targetTypeValidator,
+    targetHost: v.optional(v.string()),
+    targetPort: v.optional(v.number()),
+    targetUsername: v.optional(v.string()),
+    timeoutMs: v.optional(v.number()),
+    createdBy: v.string(),
+  },
+  returns: v.id("commandQueue"),
+  handler: async (ctx, args) => {
+    const now = Date.now();
+
+    // Validate SSH target details if targetType is ssh
+    if (args.targetType === "ssh") {
+      if (!args.targetHost || !args.targetUsername) {
+        throw new Error("SSH target requires targetHost and targetUsername");
+      }
+    }
+
+    return await ctx.db.insert("commandQueue", {
+      machineId: args.machineId,
+      command: args.command,
+      targetType: args.targetType,
+      targetHost: args.targetHost,
+      targetPort: args.targetPort ?? 22,
+      targetUsername: args.targetUsername,
+      timeoutMs: args.timeoutMs ?? 30000,
+      status: "pending",
+      createdBy: args.createdBy,
+      createdAt: now,
+      updatedAt: now,
+    });
+  },
+});
+
+/**
+ * Get pending commands for a machine
+ */
+export const listPending = query({
+  args: {
+    machineId: v.string(),
+    limit: v.optional(v.number()),
+  },
+  returns: v.array(
+    v.object({
+      _id: v.id("commandQueue"),
+      machineId: v.string(),
+      command: v.string(),
+      targetType: targetTypeValidator,
+      targetHost: v.optional(v.string()),
+      targetPort: v.optional(v.number()),
+      targetUsername: v.optional(v.string()),
+      timeoutMs: v.number(),
+      status: commandStatusValidator,
+      createdBy: v.string(),
+      createdAt: v.number(),
+    })
+  ),
+  handler: async (ctx, args) => {
+    const commands = await ctx.db
+      .query("commandQueue")
+      .withIndex("by_machineId_status", (q) =>
+        q.eq("machineId", args.machineId).eq("status", "pending")
+      )
+      .order("asc")
+      .take(args.limit ?? 10);
+
+    return commands.map((c) => ({
+      _id: c._id,
+      machineId: c.machineId,
+      command: c.command,
+      targetType: c.targetType,
+      targetHost: c.targetHost,
+      targetPort: c.targetPort,
+      targetUsername: c.targetUsername,
+      timeoutMs: c.timeoutMs,
+      status: c.status,
+      createdBy: c.createdBy,
+      createdAt: c.createdAt,
+    }));
+  },
+});
+
+/**
+ * Get a command by ID
+ */
+export const get = query({
+  args: {
+    id: v.id("commandQueue"),
+  },
+  returns: v.union(
+    v.object({
+      _id: v.id("commandQueue"),
+      machineId: v.string(),
+      command: v.string(),
+      targetType: targetTypeValidator,
+      targetHost: v.optional(v.string()),
+      targetPort: v.optional(v.number()),
+      targetUsername: v.optional(v.string()),
+      timeoutMs: v.number(),
+      status: commandStatusValidator,
+      claimedBy: v.optional(v.string()),
+      claimedAt: v.optional(v.number()),
+      output: v.optional(v.string()),
+      stderr: v.optional(v.string()),
+      exitCode: v.optional(v.number()),
+      error: v.optional(v.string()),
+      durationMs: v.optional(v.number()),
+      completedAt: v.optional(v.number()),
+      createdBy: v.string(),
+      createdAt: v.number(),
+      updatedAt: v.number(),
+    }),
+    v.null()
+  ),
+  handler: async (ctx, args) => {
+    const cmd = await ctx.db.get(args.id);
+    if (!cmd) return null;
+
+    return {
+      _id: cmd._id,
+      machineId: cmd.machineId,
+      command: cmd.command,
+      targetType: cmd.targetType,
+      targetHost: cmd.targetHost,
+      targetPort: cmd.targetPort,
+      targetUsername: cmd.targetUsername,
+      timeoutMs: cmd.timeoutMs,
+      status: cmd.status,
+      claimedBy: cmd.claimedBy,
+      claimedAt: cmd.claimedAt,
+      output: cmd.output,
+      stderr: cmd.stderr,
+      exitCode: cmd.exitCode,
+      error: cmd.error,
+      durationMs: cmd.durationMs,
+      completedAt: cmd.completedAt,
+      createdBy: cmd.createdBy,
+      createdAt: cmd.createdAt,
+      updatedAt: cmd.updatedAt,
+    };
+  },
+});
+
+/**
+ * Claim a command for execution
+ */
+export const claim = mutation({
+  args: {
+    id: v.id("commandQueue"),
+    claimedBy: v.string(), // Relay assignment ID
+  },
+  returns: v.boolean(),
+  handler: async (ctx, args) => {
+    const cmd = await ctx.db.get(args.id);
+    if (!cmd) {
+      throw new Error("Command not found");
+    }
+
+    // Only claim pending commands
+    if (cmd.status !== "pending") {
+      return false;
+    }
+
+    await ctx.db.patch(args.id, {
+      status: "claimed",
+      claimedBy: args.claimedBy,
+      claimedAt: Date.now(),
+      updatedAt: Date.now(),
+    });
+
+    return true;
+  },
+});
+
+/**
+ * Mark a command as executing
+ */
+export const startExecution = mutation({
+  args: {
+    id: v.id("commandQueue"),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const cmd = await ctx.db.get(args.id);
+    if (!cmd) {
+      throw new Error("Command not found");
+    }
+
+    await ctx.db.patch(args.id, {
+      status: "executing",
+      updatedAt: Date.now(),
+    });
+    return null;
+  },
+});
+
+/**
+ * Complete a command with results
+ */
+export const complete = mutation({
+  args: {
+    id: v.id("commandQueue"),
+    success: v.boolean(),
+    output: v.optional(v.string()),
+    stderr: v.optional(v.string()),
+    exitCode: v.optional(v.number()),
+    error: v.optional(v.string()),
+    durationMs: v.optional(v.number()),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const cmd = await ctx.db.get(args.id);
+    if (!cmd) {
+      throw new Error("Command not found");
+    }
+
+    const now = Date.now();
+
+    await ctx.db.patch(args.id, {
+      status: args.success ? "completed" : "failed",
+      output: args.output,
+      stderr: args.stderr,
+      exitCode: args.exitCode,
+      error: args.error,
+      durationMs: args.durationMs,
+      completedAt: now,
+      updatedAt: now,
+    });
+    return null;
+  },
+});
+
+/**
+ * List recent commands for a machine
+ */
+export const listRecent = query({
+  args: {
+    machineId: v.string(),
+    limit: v.optional(v.number()),
+  },
+  returns: v.array(
+    v.object({
+      _id: v.id("commandQueue"),
+      machineId: v.string(),
+      command: v.string(),
+      targetType: targetTypeValidator,
+      status: commandStatusValidator,
+      exitCode: v.optional(v.number()),
+      error: v.optional(v.string()),
+      durationMs: v.optional(v.number()),
+      createdAt: v.number(),
+      completedAt: v.optional(v.number()),
+    })
+  ),
+  handler: async (ctx, args) => {
+    const commands = await ctx.db
+      .query("commandQueue")
+      .withIndex("by_machineId", (q) => q.eq("machineId", args.machineId))
+      .order("desc")
+      .take(args.limit ?? 50);
+
+    return commands.map((c) => ({
+      _id: c._id,
+      machineId: c.machineId,
+      command: c.command,
+      targetType: c.targetType,
+      status: c.status,
+      exitCode: c.exitCode,
+      error: c.error,
+      durationMs: c.durationMs,
+      createdAt: c.createdAt,
+      completedAt: c.completedAt,
+    }));
+  },
+});

package/src/component.ts

@@ -0,0 +1,11 @@
+// Re-export all component modules for easy importing
+export { default as component } from "./convex.config.js";
+export { default as schema } from "./schema.js";
+
+// Export all functions
+export * as assignments from "./assignments.js";
+export * as commands from "./commands.js";
+export * as status from "./status.js";
+export * as credentials from "./credentials.js";
+export * as configPush from "./configPush.js";
+export * as publicApi from "./public.js";