@fatagnus/remote-cmd-relay-convex 1.0.0

package/src/_generated/server.ts

@@ -0,0 +1,161 @@
+/* eslint-disable */
+/**
+ * Generated utilities for implementing server-side Convex query and mutation functions.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type {
+  ActionBuilder,
+  HttpActionBuilder,
+  MutationBuilder,
+  QueryBuilder,
+  GenericActionCtx,
+  GenericMutationCtx,
+  GenericQueryCtx,
+  GenericDatabaseReader,
+  GenericDatabaseWriter,
+} from "convex/server";
+import {
+  actionGeneric,
+  httpActionGeneric,
+  queryGeneric,
+  mutationGeneric,
+  internalActionGeneric,
+  internalMutationGeneric,
+  internalQueryGeneric,
+} from "convex/server";
+import type { DataModel } from "./dataModel.js";
+
+/**
+ * Define a query in this Convex app's public API.
+ *
+ * This function will be allowed to read your Convex database and will be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const query: QueryBuilder<DataModel, "public"> = queryGeneric;
+
+/**
+ * Define a query that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to read from your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const internalQuery: QueryBuilder<DataModel, "internal"> =
+  internalQueryGeneric;
+
+/**
+ * Define a mutation in this Convex app's public API.
+ *
+ * This function will be allowed to modify your Convex database and will be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const mutation: MutationBuilder<DataModel, "public"> = mutationGeneric;
+
+/**
+ * Define a mutation that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to modify your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const internalMutation: MutationBuilder<DataModel, "internal"> =
+  internalMutationGeneric;
+
+/**
+ * Define an action in this Convex app's public API.
+ *
+ * An action is a function which can execute any JavaScript code, including non-deterministic
+ * code and code with side-effects, like calling third-party services.
+ * They can be run in Convex's JavaScript environment or in Node.js using the "use node" directive.
+ * They can interact with the database indirectly by calling queries and mutations using the {@link ActionCtx}.
+ *
+ * @param func - The action. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped action. Include this as an `export` to name it and make it accessible.
+ */
+export const action: ActionBuilder<DataModel, "public"> = actionGeneric;
+
+/**
+ * Define an action that is only accessible from other Convex functions (but not from the client).
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped function. Include this as an `export` to name it and make it accessible.
+ */
+export const internalAction: ActionBuilder<DataModel, "internal"> =
+  internalActionGeneric;
+
+/**
+ * Define an HTTP action.
+ *
+ * The wrapped function will be used to respond to HTTP requests received
+ * by a Convex deployment if the requests matches the path and method where
+ * this action is routed. Be sure to route your httpAction in `convex/http.js`.
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument
+ * and a Fetch API `Request` object as its second.
+ * @returns The wrapped function. Import this function from `convex/http.js` and route it to hook it up.
+ */
+export const httpAction: HttpActionBuilder = httpActionGeneric;
+
+type GenericCtx =
+  | GenericActionCtx<DataModel>
+  | GenericMutationCtx<DataModel>
+  | GenericQueryCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex query functions.
+ *
+ * The query context is passed as the first argument to any Convex query
+ * function run on the server.
+ *
+ * If you're using code generation, use the `QueryCtx` type in `convex/_generated/server.d.ts` instead.
+ */
+export type QueryCtx = GenericQueryCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex mutation functions.
+ *
+ * The mutation context is passed as the first argument to any Convex mutation
+ * function run on the server.
+ *
+ * If you're using code generation, use the `MutationCtx` type in `convex/_generated/server.d.ts` instead.
+ */
+export type MutationCtx = GenericMutationCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex action functions.
+ *
+ * The action context is passed as the first argument to any Convex action
+ * function run on the server.
+ */
+export type ActionCtx = GenericActionCtx<DataModel>;
+
+/**
+ * An interface to read from the database within Convex query functions.
+ *
+ * The two entry points are {@link DatabaseReader.get}, which fetches a single
+ * document by its {@link Id}, or {@link DatabaseReader.query}, which starts
+ * building a query.
+ */
+export type DatabaseReader = GenericDatabaseReader<DataModel>;
+
+/**
+ * An interface to read from and write to the database within Convex mutation
+ * functions.
+ *
+ * Convex guarantees that all writes within a single mutation are
+ * executed atomically, so you never have to worry about partial writes leaving
+ * your data in an inconsistent state. See [the Convex Guide](https://docs.convex.dev/understanding/convex-fundamentals/functions#atomicity-and-optimistic-concurrency-control)
+ * for the guarantees Convex provides your functions.
+ */
+export type DatabaseWriter = GenericDatabaseWriter<DataModel>;

package/src/assignments.test.ts

@@ -0,0 +1,233 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import {
+  createRelayTestConvex,
+  createTestRelayAssignment,
+  type RelayTestConvex,
+} from "./test.setup";
+import { api } from "./_generated/api";
+
+describe("relay assignments", () => {
+  let t: RelayTestConvex;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    t = createRelayTestConvex();
+  });
+
+  afterEach(async () => {
+    await t.finishAllScheduledFunctions(vi.runAllTimers);
+    vi.useRealTimers();
+  });
+
+  describe("create", () => {
+    it("creates a relay assignment", async () => {
+      const result = await t.mutation(api.assignments.create, {
+        apiKeyId: "api-key-123",
+        machineId: "machine-456",
+        name: "Test Relay",
+        createdBy: "user-789",
+      });
+
+      expect(result).toBeDefined();
+
+      // Verify the assignment was created
+      const assignment = await t.run(async (ctx) => {
+        return await ctx.db.get(result);
+      });
+
+      expect(assignment).not.toBeNull();
+      expect(assignment?.apiKeyId).toBe("api-key-123");
+      expect(assignment?.machineId).toBe("machine-456");
+      expect(assignment?.name).toBe("Test Relay");
+      expect(assignment?.enabled).toBe(true);
+    });
+
+    it("prevents duplicate API key assignments", async () => {
+      await t.mutation(api.assignments.create, {
+        apiKeyId: "api-key-duplicate",
+        machineId: "machine-1",
+        name: "First Relay",
+        createdBy: "user-1",
+      });
+
+      await expect(
+        t.mutation(api.assignments.create, {
+          apiKeyId: "api-key-duplicate",
+          machineId: "machine-2",
+          name: "Second Relay",
+          createdBy: "user-1",
+        })
+      ).rejects.toThrow("API key is already assigned to a machine");
+    });
+  });
+
+  describe("getByApiKeyId", () => {
+    it("returns assignment by API key ID", async () => {
+      const created = await createTestRelayAssignment(t, {
+        apiKeyId: "lookup-key",
+        name: "Lookup Relay",
+      });
+
+      const result = await t.query(api.assignments.getByApiKeyId, {
+        apiKeyId: "lookup-key",
+      });
+
+      expect(result).not.toBeNull();
+      expect(result?._id).toBe(created._id);
+      expect(result?.name).toBe("Lookup Relay");
+    });
+
+    it("returns null for unknown API key", async () => {
+      const result = await t.query(api.assignments.getByApiKeyId, {
+        apiKeyId: "unknown-key",
+      });
+
+      expect(result).toBeNull();
+    });
+  });
+
+  describe("listByMachineId", () => {
+    it("lists assignments for a machine", async () => {
+      await createTestRelayAssignment(t, {
+        machineId: "target-machine",
+        apiKeyId: "key-1",
+        name: "Relay 1",
+      });
+      await createTestRelayAssignment(t, {
+        machineId: "target-machine",
+        apiKeyId: "key-2",
+        name: "Relay 2",
+      });
+      await createTestRelayAssignment(t, {
+        machineId: "other-machine",
+        apiKeyId: "key-3",
+        name: "Other Relay",
+      });
+
+      const result = await t.query(api.assignments.listByMachineId, {
+        machineId: "target-machine",
+      });
+
+      expect(result).toHaveLength(2);
+      expect(result.map((r) => r.name).sort()).toEqual(["Relay 1", "Relay 2"]);
+    });
+
+    it("returns empty array for machine with no assignments", async () => {
+      const result = await t.query(api.assignments.listByMachineId, {
+        machineId: "no-assignments-machine",
+      });
+
+      expect(result).toHaveLength(0);
+    });
+  });
+
+  describe("listAll", () => {
+    it("lists all assignments", async () => {
+      await createTestRelayAssignment(t, { apiKeyId: "key-a", name: "Relay A" });
+      await createTestRelayAssignment(t, { apiKeyId: "key-b", name: "Relay B" });
+
+      const result = await t.query(api.assignments.listAll, {});
+
+      expect(result).toHaveLength(2);
+    });
+  });
+
+  describe("update", () => {
+    it("updates assignment name", async () => {
+      const created = await createTestRelayAssignment(t, {
+        name: "Original Name",
+      });
+
+      await t.mutation(api.assignments.update, {
+        id: created._id,
+        name: "Updated Name",
+      });
+
+      const updated = await t.run(async (ctx) => {
+        return await ctx.db.get(created._id);
+      });
+
+      expect(updated?.name).toBe("Updated Name");
+    });
+
+    it("updates assignment enabled status", async () => {
+      const created = await createTestRelayAssignment(t, {
+        enabled: true,
+      });
+
+      await t.mutation(api.assignments.update, {
+        id: created._id,
+        enabled: false,
+      });
+
+      const updated = await t.run(async (ctx) => {
+        return await ctx.db.get(created._id);
+      });
+
+      expect(updated?.enabled).toBe(false);
+    });
+
+    it("throws for non-existent assignment", async () => {
+      // Create and delete an assignment to get a valid but non-existent ID
+      const created = await createTestRelayAssignment(t);
+      await t.run(async (ctx) => {
+        await ctx.db.delete(created._id);
+      });
+
+      await expect(
+        t.mutation(api.assignments.update, {
+          id: created._id,
+          name: "Will Fail",
+        })
+      ).rejects.toThrow("Relay assignment not found");
+    });
+  });
+
+  describe("heartbeat", () => {
+    it("updates lastSeenAt timestamp", async () => {
+      const created = await createTestRelayAssignment(t, {
+        apiKeyId: "heartbeat-key",
+      });
+
+      // Verify no lastSeenAt initially
+      const before = await t.run(async (ctx) => {
+        return await ctx.db.get(created._id);
+      });
+      expect(before?.lastSeenAt).toBeUndefined();
+
+      // Send heartbeat
+      await t.mutation(api.assignments.heartbeat, {
+        apiKeyId: "heartbeat-key",
+      });
+
+      const after = await t.run(async (ctx) => {
+        return await ctx.db.get(created._id);
+      });
+
+      expect(after?.lastSeenAt).toBeDefined();
+    });
+
+    it("does nothing for unknown API key", async () => {
+      // Should not throw
+      await t.mutation(api.assignments.heartbeat, {
+        apiKeyId: "unknown-heartbeat-key",
+      });
+    });
+  });
+
+  describe("remove", () => {
+    it("deletes an assignment", async () => {
+      const created = await createTestRelayAssignment(t);
+
+      await t.mutation(api.assignments.remove, {
+        id: created._id,
+      });
+
+      const deleted = await t.run(async (ctx) => {
+        return await ctx.db.get(created._id);
+      });
+
+      expect(deleted).toBeNull();
+    });
+  });
+});

package/src/assignments.ts

@@ -0,0 +1,222 @@
+import { v } from "convex/values";
+import { mutation, query } from "./_generated/server";
+
+/**
+ * Create a new relay assignment linking an API key to a machine
+ */
+export const create = mutation({
+  args: {
+    apiKeyId: v.string(),
+    machineId: v.string(),
+    name: v.string(),
+    createdBy: v.string(),
+  },
+  returns: v.id("relayAssignments"),
+  handler: async (ctx, args) => {
+    const now = Date.now();
+
+    // Check if assignment already exists for this API key
+    const existing = await ctx.db
+      .query("relayAssignments")
+      .withIndex("by_apiKeyId", (q) => q.eq("apiKeyId", args.apiKeyId))
+      .first();
+
+    if (existing) {
+      throw new Error("API key is already assigned to a machine");
+    }
+
+    return await ctx.db.insert("relayAssignments", {
+      apiKeyId: args.apiKeyId,
+      machineId: args.machineId,
+      name: args.name,
+      enabled: true,
+      createdBy: args.createdBy,
+      createdAt: now,
+      updatedAt: now,
+    });
+  },
+});
+
+/**
+ * Get a relay assignment by API key ID
+ */
+export const getByApiKeyId = query({
+  args: {
+    apiKeyId: v.string(),
+  },
+  returns: v.union(
+    v.object({
+      _id: v.id("relayAssignments"),
+      apiKeyId: v.string(),
+      machineId: v.string(),
+      name: v.string(),
+      enabled: v.boolean(),
+      lastSeenAt: v.optional(v.number()),
+      createdBy: v.string(),
+      createdAt: v.number(),
+      updatedAt: v.number(),
+    }),
+    v.null()
+  ),
+  handler: async (ctx, args) => {
+    const assignment = await ctx.db
+      .query("relayAssignments")
+      .withIndex("by_apiKeyId", (q) => q.eq("apiKeyId", args.apiKeyId))
+      .first();
+
+    if (!assignment) return null;
+
+    return {
+      _id: assignment._id,
+      apiKeyId: assignment.apiKeyId,
+      machineId: assignment.machineId,
+      name: assignment.name,
+      enabled: assignment.enabled,
+      lastSeenAt: assignment.lastSeenAt,
+      createdBy: assignment.createdBy,
+      createdAt: assignment.createdAt,
+      updatedAt: assignment.updatedAt,
+    };
+  },
+});
+
+/**
+ * List all relay assignments for a machine
+ */
+export const listByMachineId = query({
+  args: {
+    machineId: v.string(),
+  },
+  returns: v.array(
+    v.object({
+      _id: v.id("relayAssignments"),
+      apiKeyId: v.string(),
+      machineId: v.string(),
+      name: v.string(),
+      enabled: v.boolean(),
+      lastSeenAt: v.optional(v.number()),
+      createdBy: v.string(),
+      createdAt: v.number(),
+      updatedAt: v.number(),
+    })
+  ),
+  handler: async (ctx, args) => {
+    const assignments = await ctx.db
+      .query("relayAssignments")
+      .withIndex("by_machineId", (q) => q.eq("machineId", args.machineId))
+      .collect();
+
+    return assignments.map((a) => ({
+      _id: a._id,
+      apiKeyId: a.apiKeyId,
+      machineId: a.machineId,
+      name: a.name,
+      enabled: a.enabled,
+      lastSeenAt: a.lastSeenAt,
+      createdBy: a.createdBy,
+      createdAt: a.createdAt,
+      updatedAt: a.updatedAt,
+    }));
+  },
+});
+
+/**
+ * Update relay assignment
+ */
+export const update = mutation({
+  args: {
+    id: v.id("relayAssignments"),
+    name: v.optional(v.string()),
+    enabled: v.optional(v.boolean()),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const { id, ...updates } = args;
+    const existing = await ctx.db.get(id);
+    if (!existing) {
+      throw new Error("Relay assignment not found");
+    }
+
+    await ctx.db.patch(id, {
+      ...updates,
+      updatedAt: Date.now(),
+    });
+    return null;
+  },
+});
+
+/**
+ * Update last seen timestamp for a relay
+ */
+export const heartbeat = mutation({
+  args: {
+    apiKeyId: v.string(),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    const assignment = await ctx.db
+      .query("relayAssignments")
+      .withIndex("by_apiKeyId", (q) => q.eq("apiKeyId", args.apiKeyId))
+      .first();
+
+    if (assignment) {
+      await ctx.db.patch(assignment._id, {
+        lastSeenAt: Date.now(),
+        updatedAt: Date.now(),
+      });
+    }
+    return null;
+  },
+});
+
+/**
+ * List all relay assignments (for admin view)
+ */
+export const listAll = query({
+  args: {},
+  returns: v.array(
+    v.object({
+      _id: v.id("relayAssignments"),
+      apiKeyId: v.string(),
+      machineId: v.string(),
+      name: v.string(),
+      enabled: v.boolean(),
+      lastSeenAt: v.optional(v.number()),
+      createdBy: v.string(),
+      createdAt: v.number(),
+      updatedAt: v.number(),
+    })
+  ),
+  handler: async (ctx) => {
+    const assignments = await ctx.db
+      .query("relayAssignments")
+      .order("desc")
+      .collect();
+
+    return assignments.map((a) => ({
+      _id: a._id,
+      apiKeyId: a.apiKeyId,
+      machineId: a.machineId,
+      name: a.name,
+      enabled: a.enabled,
+      lastSeenAt: a.lastSeenAt,
+      createdBy: a.createdBy,
+      createdAt: a.createdAt,
+      updatedAt: a.updatedAt,
+    }));
+  },
+});
+
+/**
+ * Delete a relay assignment
+ */
+export const remove = mutation({
+  args: {
+    id: v.id("relayAssignments"),
+  },
+  returns: v.null(),
+  handler: async (ctx, args) => {
+    await ctx.db.delete(args.id);
+    return null;
+  },
+});