@fatagnus/remote-cmd-relay-convex 2.0.0 → 2.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fatagnus/remote-cmd-relay-convex",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Convex component for managing remote command relays - assignment management, command queuing, status tracking, and credential inventory",
   "author": "Ozan Turksever <ozan.turksever@gmail.com>",
   "license": "Apache-2.0",

package/src/_generated/component.ts

@@ -457,6 +457,13 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         { success: boolean },
         Name
       >;
+      updatePartialOutput: FunctionReference<
+        "mutation",
+        "internal",
+        { commandId: string; partialOutput?: string; partialStderr?: string },
+        { success: boolean },
+        Name
+      >;
       verifyRelay: FunctionReference<
         "query",
         "internal",
@@ -489,6 +496,30 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         | { found: false },
         Name
       >;
+      getCommandStream: FunctionReference<
+        "query",
+        "internal",
+        { commandId: string; outputOffset?: number },
+        | {
+            done: boolean;
+            error?: string;
+            exitCode?: number;
+            found: true;
+            output?: string;
+            partialOutput?: string;
+            partialStderr?: string;
+            status:
+              | "pending"
+              | "claimed"
+              | "executing"
+              | "completed"
+              | "failed"
+              | "timeout";
+            stderr?: string;
+          }
+        | { found: false },
+        Name
+      >;
       queueRpcCommand: FunctionReference<
         "mutation",
         "internal",

package/src/_generated/dataModel.ts

@@ -38,7 +38,7 @@ export type Doc<TableName extends TableNames> = DocumentByName<
  * Convex documents are uniquely identified by their `Id`, which is accessible
  * on the `_id` field. To learn more, see [Document IDs](https://docs.convex.dev/using/document-ids).
  *
- * Documents can be loaded using `db.get(tableName, id)` in query and mutation functions.
+ * Documents can be loaded using `db.get(id)` in query and mutation functions.
  *
  * IDs are just strings at runtime, but this type can be used to distinguish them from other
  * strings when type checking.

package/src/public.test.ts

@@ -185,6 +185,130 @@ describe("public", () => {
     });
   });
 
+  describe("updatePartialOutput", () => {
+    it("updates partial output for claimed command", async () => {
+      const cmd = await createMockCommand(t, {
+        status: "claimed",
+        claimedBy: "relay-1",
+      });
+
+      const result = await t.mutation(api.public.updatePartialOutput, {
+        commandId: cmd._id,
+        partialOutput: "Processing...\n",
+        partialStderr: "",
+      });
+
+      expect(result.success).toBe(true);
+
+      // Verify command was updated
+      const updated = await t.run(async (ctx) => {
+        return await ctx.db.get(cmd._id);
+      });
+
+      expect(updated?.status).toBe("executing");
+      expect(updated?.partialOutput).toBe("Processing...\n");
+    });
+
+    it("updates partial output for executing command", async () => {
+      const cmd = await createMockCommand(t, {
+        status: "executing",
+      });
+
+      await t.run(async (ctx) => {
+        await ctx.db.patch(cmd._id, {
+          partialOutput: "Line 1\n",
+        });
+      });
+
+      const result = await t.mutation(api.public.updatePartialOutput, {
+        commandId: cmd._id,
+        partialOutput: "Line 1\nLine 2\n",
+      });
+
+      expect(result.success).toBe(true);
+
+      const updated = await t.run(async (ctx) => {
+        return await ctx.db.get(cmd._id);
+      });
+
+      expect(updated?.partialOutput).toBe("Line 1\nLine 2\n");
+    });
+
+    it("updates both stdout and stderr", async () => {
+      const cmd = await createMockCommand(t, {
+        status: "claimed",
+      });
+
+      const result = await t.mutation(api.public.updatePartialOutput, {
+        commandId: cmd._id,
+        partialOutput: "stdout content",
+        partialStderr: "stderr content",
+      });
+
+      expect(result.success).toBe(true);
+
+      const updated = await t.run(async (ctx) => {
+        return await ctx.db.get(cmd._id);
+      });
+
+      expect(updated?.partialOutput).toBe("stdout content");
+      expect(updated?.partialStderr).toBe("stderr content");
+    });
+
+    it("fails for non-existent command", async () => {
+      const cmd = await createMockCommand(t, { status: "pending" });
+      await t.run(async (ctx) => {
+        await ctx.db.delete(cmd._id);
+      });
+
+      const result = await t.mutation(api.public.updatePartialOutput, {
+        commandId: cmd._id,
+        partialOutput: "test",
+      });
+
+      expect(result.success).toBe(false);
+    });
+
+    it("fails for completed command", async () => {
+      const cmd = await createMockCommand(t, {
+        status: "completed",
+      });
+
+      const result = await t.mutation(api.public.updatePartialOutput, {
+        commandId: cmd._id,
+        partialOutput: "test",
+      });
+
+      expect(result.success).toBe(false);
+    });
+
+    it("fails for failed command", async () => {
+      const cmd = await createMockCommand(t, {
+        status: "failed",
+      });
+
+      const result = await t.mutation(api.public.updatePartialOutput, {
+        commandId: cmd._id,
+        partialOutput: "test",
+      });
+
+      expect(result.success).toBe(false);
+    });
+
+    it("fails for pending command (not yet claimed)", async () => {
+      const cmd = await createMockCommand(t, {
+        status: "pending",
+      });
+
+      const result = await t.mutation(api.public.updatePartialOutput, {
+        commandId: cmd._id,
+        partialOutput: "test",
+      });
+
+      expect(result.success).toBe(false);
+    });
+  });
+
   describe("submitResult", () => {
     it("submits successful command result", async () => {
       const cmd = await createMockCommand(t, {

package/src/public.ts

@@ -150,6 +150,46 @@ export const claimCommand = mutation({
   },
 });
 
+/**
+ * Update partial output during command execution (for streaming)
+ */
+export const updatePartialOutput = mutation({
+  args: {
+    commandId: v.id("commandQueue"),
+    partialOutput: v.optional(v.string()),
+    partialStderr: v.optional(v.string()),
+  },
+  returns: v.object({
+    success: v.boolean(),
+  }),
+  handler: async (ctx, args) => {
+    const cmd = await ctx.db.get(args.commandId);
+    if (!cmd) {
+      return { success: false };
+    }
+
+    // Only update if command is still executing
+    if (cmd.status !== "claimed" && cmd.status !== "executing") {
+      return { success: false };
+    }
+
+    const updates: Record<string, unknown> = {
+      status: "executing",
+      updatedAt: Date.now(),
+    };
+
+    if (args.partialOutput !== undefined) {
+      updates.partialOutput = args.partialOutput;
+    }
+    if (args.partialStderr !== undefined) {
+      updates.partialStderr = args.partialStderr;
+    }
+
+    await ctx.db.patch(args.commandId, updates);
+    return { success: true };
+  },
+});
+
 /**
  * Submit command execution results
  */

package/src/rpc.test.ts

@@ -293,6 +293,328 @@ describe("rpc", () => {
     });
   });
 
+  describe("getCommandStream", () => {
+    it("returns found: false for non-existent command", async () => {
+      const cmd = await createMockCommand(t, { status: "pending" });
+      await t.run(async (ctx) => {
+        await ctx.db.delete(cmd._id);
+      });
+
+      const result = await t.query(api.rpc.getCommandStream, {
+        commandId: cmd._id,
+      });
+
+      expect(result.found).toBe(false);
+    });
+
+    it("returns partial output for executing command", async () => {
+      const cmd = await createMockCommand(t, {
+        machineId: "machine-1",
+        status: "executing",
+      });
+
+      await t.run(async (ctx) => {
+        await ctx.db.patch(cmd._id, {
+          partialOutput: "Processing line 1\nProcessing line 2\n",
+          partialStderr: "Warning: something\n",
+        });
+      });
+
+      const result = await t.query(api.rpc.getCommandStream, {
+        commandId: cmd._id,
+      });
+
+      expect(result.found).toBe(true);
+      if (result.found) {
+        expect(result.status).toBe("executing");
+        expect(result.partialOutput).toBe("Processing line 1\nProcessing line 2\n");
+        expect(result.partialStderr).toBe("Warning: something\n");
+        expect(result.done).toBe(false);
+        expect(result.output).toBeUndefined();
+      }
+    });
+
+    it("returns partial output with offset", async () => {
+      const cmd = await createMockCommand(t, {
+        machineId: "machine-1",
+        status: "executing",
+      });
+
+      await t.run(async (ctx) => {
+        await ctx.db.patch(cmd._id, {
+          partialOutput: "Line 1\nLine 2\nLine 3\n",
+        });
+      });
+
+      // Request output starting from offset 7 (after "Line 1\n")
+      const result = await t.query(api.rpc.getCommandStream, {
+        commandId: cmd._id,
+        outputOffset: 7,
+      });
+
+      expect(result.found).toBe(true);
+      if (result.found) {
+        expect(result.partialOutput).toBe("Line 2\nLine 3\n");
+        expect(result.done).toBe(false);
+      }
+    });
+
+    it("returns final output when command is completed", async () => {
+      const cmd = await createMockCommand(t, {
+        machineId: "machine-1",
+        status: "completed",
+      });
+
+      await t.run(async (ctx) => {
+        await ctx.db.patch(cmd._id, {
+          output: "Final output\n",
+          stderr: "Final stderr\n",
+          exitCode: 0,
+          partialOutput: "Should be ignored",
+        });
+      });
+
+      const result = await t.query(api.rpc.getCommandStream, {
+        commandId: cmd._id,
+      });
+
+      expect(result.found).toBe(true);
+      if (result.found) {
+        expect(result.status).toBe("completed");
+        expect(result.output).toBe("Final output\n");
+        expect(result.stderr).toBe("Final stderr\n");
+        expect(result.exitCode).toBe(0);
+        expect(result.done).toBe(true);
+        expect(result.partialOutput).toBeUndefined();
+      }
+    });
+
+    it("returns done: true for failed command", async () => {
+      const cmd = await createMockCommand(t, {
+        machineId: "machine-1",
+        status: "failed",
+      });
+
+      await t.run(async (ctx) => {
+        await ctx.db.patch(cmd._id, {
+          stderr: "Error message",
+          exitCode: 1,
+          error: "Command failed",
+        });
+      });
+
+      const result = await t.query(api.rpc.getCommandStream, {
+        commandId: cmd._id,
+      });
+
+      expect(result.found).toBe(true);
+      if (result.found) {
+        expect(result.status).toBe("failed");
+        expect(result.done).toBe(true);
+        expect(result.error).toBe("Command failed");
+      }
+    });
+
+    it("returns done: true for timeout command", async () => {
+      const cmd = await createMockCommand(t, {
+        machineId: "machine-1",
+        status: "timeout",
+      });
+
+      await t.run(async (ctx) => {
+        await ctx.db.patch(cmd._id, {
+          error: "Command timed out",
+        });
+      });
+
+      const result = await t.query(api.rpc.getCommandStream, {
+        commandId: cmd._id,
+      });
+
+      expect(result.found).toBe(true);
+      if (result.found) {
+        expect(result.status).toBe("timeout");
+        expect(result.done).toBe(true);
+      }
+    });
+
+    it("returns empty partial output for pending command", async () => {
+      const cmd = await createMockCommand(t, {
+        machineId: "machine-1",
+        status: "pending",
+      });
+
+      const result = await t.query(api.rpc.getCommandStream, {
+        commandId: cmd._id,
+      });
+
+      expect(result.found).toBe(true);
+      if (result.found) {
+        expect(result.status).toBe("pending");
+        expect(result.done).toBe(false);
+        expect(result.partialOutput).toBeUndefined();
+      }
+    });
+
+    it("returns empty partial output for claimed command", async () => {
+      const cmd = await createMockCommand(t, {
+        machineId: "machine-1",
+        status: "claimed",
+        claimedBy: "relay-1",
+      });
+
+      const result = await t.query(api.rpc.getCommandStream, {
+        commandId: cmd._id,
+      });
+
+      expect(result.found).toBe(true);
+      if (result.found) {
+        expect(result.status).toBe("claimed");
+        expect(result.done).toBe(false);
+      }
+    });
+  });
+
+  describe("streaming workflow", () => {
+    it("simulates real-time streaming: queue -> claim -> stream updates -> complete", async () => {
+      // 1. Queue command
+      const queueResult = await t.mutation(api.rpc.queueRpcCommand, {
+        machineId: "stream-machine",
+        command: "long-running-command",
+        targetType: "local",
+        createdBy: "test-user",
+      });
+
+      expect(queueResult.success).toBe(true);
+      const commandId = queueResult.commandId!;
+
+      // 2. Verify command is pending, no streaming data
+      let streamResult = await t.query(api.rpc.getCommandStream, { commandId });
+      expect(streamResult.found).toBe(true);
+      if (streamResult.found) {
+        expect(streamResult.status).toBe("pending");
+        expect(streamResult.done).toBe(false);
+      }
+
+      // 3. Relay claims command
+      await t.mutation(api.commands.claim, {
+        id: commandId,
+        claimedBy: "relay-1",
+      });
+
+      // 4. Relay sends first streaming update
+      await t.mutation(api.public.updatePartialOutput, {
+        commandId,
+        partialOutput: "Step 1: Starting...\n",
+      });
+
+      streamResult = await t.query(api.rpc.getCommandStream, { commandId });
+      if (streamResult.found) {
+        expect(streamResult.status).toBe("executing");
+        expect(streamResult.partialOutput).toBe("Step 1: Starting...\n");
+        expect(streamResult.done).toBe(false);
+      }
+
+      // 5. Relay sends second streaming update
+      await t.mutation(api.public.updatePartialOutput, {
+        commandId,
+        partialOutput: "Step 1: Starting...\nStep 2: Processing...\n",
+      });
+
+      // Client polls with offset to get only new content
+      streamResult = await t.query(api.rpc.getCommandStream, {
+        commandId,
+        outputOffset: 20, // Length of first message
+      });
+      if (streamResult.found) {
+        expect(streamResult.partialOutput).toBe("Step 2: Processing...\n");
+      }
+
+      // 6. Relay sends third streaming update with stderr
+      await t.mutation(api.public.updatePartialOutput, {
+        commandId,
+        partialOutput: "Step 1: Starting...\nStep 2: Processing...\nStep 3: Finishing...\n",
+        partialStderr: "Warning: deprecated API\n",
+      });
+
+      streamResult = await t.query(api.rpc.getCommandStream, { commandId });
+      if (streamResult.found) {
+        expect(streamResult.partialStderr).toBe("Warning: deprecated API\n");
+      }
+
+      // 7. Relay completes command
+      await t.mutation(api.commands.complete, {
+        id: commandId,
+        success: true,
+        output: "Step 1: Starting...\nStep 2: Processing...\nStep 3: Finishing...\nDone!\n",
+        exitCode: 0,
+        durationMs: 5000,
+      });
+
+      // 8. Client gets final result
+      streamResult = await t.query(api.rpc.getCommandStream, { commandId });
+      if (streamResult.found) {
+        expect(streamResult.status).toBe("completed");
+        expect(streamResult.done).toBe(true);
+        expect(streamResult.output).toContain("Done!");
+        expect(streamResult.exitCode).toBe(0);
+        expect(streamResult.partialOutput).toBeUndefined();
+      }
+    });
+
+    it("streaming with command failure", async () => {
+      // 1. Queue command
+      const queueResult = await t.mutation(api.rpc.queueRpcCommand, {
+        machineId: "fail-stream-machine",
+        command: "failing-command",
+        targetType: "local",
+        createdBy: "test-user",
+      });
+
+      const commandId = queueResult.commandId!;
+
+      // 2. Claim and start streaming
+      await t.mutation(api.commands.claim, {
+        id: commandId,
+        claimedBy: "relay-1",
+      });
+
+      await t.mutation(api.public.updatePartialOutput, {
+        commandId,
+        partialOutput: "Starting...\n",
+        partialStderr: "Error: something went wrong\n",
+      });
+
+      // 3. Verify streaming state
+      let streamResult = await t.query(api.rpc.getCommandStream, { commandId });
+      if (streamResult.found) {
+        expect(streamResult.status).toBe("executing");
+        expect(streamResult.partialStderr).toBe("Error: something went wrong\n");
+        expect(streamResult.done).toBe(false);
+      }
+
+      // 4. Command fails
+      await t.mutation(api.commands.complete, {
+        id: commandId,
+        success: false,
+        output: "Starting...\n",
+        stderr: "Error: something went wrong\n",
+        exitCode: 1,
+        error: "Command failed with exit code 1",
+        durationMs: 500,
+      });
+
+      // 5. Verify final failed state
+      streamResult = await t.query(api.rpc.getCommandStream, { commandId });
+      if (streamResult.found) {
+        expect(streamResult.status).toBe("failed");
+        expect(streamResult.done).toBe(true);
+        expect(streamResult.stderr).toBe("Error: something went wrong\n");
+        expect(streamResult.exitCode).toBe(1);
+      }
+    });
+  });
+
   describe("RPC workflow integration", () => {
     it("complete RPC flow: queue -> claim -> execute -> complete -> get result", async () => {
       // 1. Queue command via RPC

package/src/rpc.ts

@@ -95,3 +95,73 @@ export const getCommandResult = query({
     };
   },
 });
+
+/**
+ * Get streaming output for a command (includes partial output during execution).
+ * Use this for real-time output streaming.
+ */
+export const getCommandStream = query({
+  args: {
+    commandId: v.id("commandQueue"),
+    outputOffset: v.optional(v.number()), // Only return output after this offset
+  },
+  returns: v.union(
+    v.object({
+      found: v.literal(true),
+      status: commandStatusValidator,
+      partialOutput: v.optional(v.string()),
+      partialStderr: v.optional(v.string()),
+      output: v.optional(v.string()),
+      stderr: v.optional(v.string()),
+      exitCode: v.optional(v.number()),
+      error: v.optional(v.string()),
+      done: v.boolean(),
+    }),
+    v.object({
+      found: v.literal(false),
+    })
+  ),
+  handler: async (ctx, args) => {
+    const cmd = await ctx.db.get(args.commandId);
+    if (!cmd) {
+      return { found: false as const };
+    }
+
+    const isDone = cmd.status === "completed" || cmd.status === "failed" || cmd.status === "timeout";
+
+    // If command is done, return final output
+    if (isDone) {
+      return {
+        found: true as const,
+        status: cmd.status,
+        partialOutput: undefined,
+        partialStderr: undefined,
+        output: cmd.output,
+        stderr: cmd.stderr,
+        exitCode: cmd.exitCode,
+        error: cmd.error,
+        done: true,
+      };
+    }
+
+    // Return partial output, optionally sliced from offset
+    let partialOutput = cmd.partialOutput;
+    let partialStderr = cmd.partialStderr;
+
+    if (args.outputOffset !== undefined && partialOutput) {
+      partialOutput = partialOutput.slice(args.outputOffset);
+    }
+
+    return {
+      found: true as const,
+      status: cmd.status,
+      partialOutput,
+      partialStderr,
+      output: undefined,
+      stderr: undefined,
+      exitCode: undefined,
+      error: undefined,
+      done: false,
+    };
+  },
+});

package/src/schema.ts

@@ -157,6 +157,10 @@ export const tables = {
     status: commandStatusValidator,
     claimedBy: v.optional(v.string()), // Relay assignment ID that claimed
     claimedAt: v.optional(v.number()),
+    // Streaming output support
+    partialOutput: v.optional(v.string()), // Incremental stdout during execution
+    partialStderr: v.optional(v.string()), // Incremental stderr during execution
+    outputOffset: v.optional(v.number()), // Last sent output offset for streaming
     // Results
     output: v.optional(v.string()),
     stderr: v.optional(v.string()),