@synnaxlabs/client 0.47.0 → 0.49.0

package/src/task/access.spec.ts

@@ -0,0 +1,131 @@
+// Copyright 2025 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+import { describe, expect, it } from "vitest";
+
+import { AuthError, NotFoundError } from "@/errors";
+import { rack } from "@/rack";
+import { task } from "@/task";
+import { createTestClientWithPolicy } from "@/testutil/access";
+import { createTestClient } from "@/testutil/client";
+
+const client = createTestClient();
+
+describe("task", () => {
+  describe("access control", () => {
+    it("should deny access when no retrieve policy exists", async () => {
+      const userClient = await createTestClientWithPolicy(client, {
+        name: "test",
+        objects: [],
+        actions: [],
+      });
+      const rack = await client.racks.create({
+        name: "test",
+      });
+      const randomTask = await rack.createTask({
+        name: "test",
+        type: "ni",
+        config: {},
+      });
+      await expect(userClient.tasks.retrieve({ key: randomTask.key })).rejects.toThrow(
+        AuthError,
+      );
+    });
+
+    it("should allow the caller to retrieve tasks with the correct policy", async () => {
+      const userClient = await createTestClientWithPolicy(client, {
+        name: "test",
+        objects: [task.ontologyID("")],
+        actions: ["retrieve"],
+      });
+      const rack = await client.racks.create({
+        name: "test",
+      });
+      const randomTask = await rack.createTask({
+        name: "test",
+        type: "ni",
+        config: {},
+      });
+      const retrieved = await userClient.tasks.retrieve({
+        key: randomTask.key,
+      });
+      expect(retrieved.key).toBe(randomTask.key);
+      expect(retrieved.name).toBe(randomTask.name);
+    });
+
+    it("should allow the caller to create tasks with the correct policy", async () => {
+      const userClient = await createTestClientWithPolicy(client, {
+        name: "test",
+        objects: [task.ontologyID(""), rack.ontologyID(0)],
+        actions: ["create", "retrieve"],
+      });
+      const rck = await client.racks.create({
+        name: "test",
+      });
+      const userRack = await userClient.racks.retrieve({ key: rck.key });
+      await userRack.createTask({
+        name: "test",
+        type: "ni",
+        config: {},
+      });
+    });
+
+    it("should deny access when no create policy exists", async () => {
+      const userClient = await createTestClientWithPolicy(client, {
+        name: "test",
+        objects: [task.ontologyID("")],
+        actions: [],
+      });
+      await expect(
+        userClient.tasks.create({
+          name: "test",
+          type: "ni",
+          config: {},
+        }),
+      ).rejects.toThrow(AuthError);
+    });
+
+    it("should allow the caller to delete tasks with the correct policy", async () => {
+      const userClient = await createTestClientWithPolicy(client, {
+        name: "test",
+        objects: [task.ontologyID("")],
+        actions: ["delete", "retrieve"],
+      });
+      const rack = await client.racks.create({
+        name: "test",
+      });
+      const randomTask = await rack.createTask({
+        name: "test",
+        type: "ni",
+        config: {},
+      });
+      await userClient.tasks.delete(randomTask.key);
+      await expect(userClient.tasks.retrieve({ key: randomTask.key })).rejects.toThrow(
+        NotFoundError,
+      );
+    });
+
+    it("should deny access when no delete policy exists", async () => {
+      const userClient = await createTestClientWithPolicy(client, {
+        name: "test",
+        objects: [task.ontologyID("")],
+        actions: [],
+      });
+      const rack = await client.racks.create({
+        name: "test",
+      });
+      const randomTask = await rack.createTask({
+        name: "test",
+        type: "ni",
+        config: {},
+      });
+      await expect(userClient.tasks.delete(randomTask.key)).rejects.toThrow(AuthError);
+    });
+  });
+});

package/src/{hardware/task → task}/client.ts

@@ -20,7 +20,10 @@ import {
 import { z } from "zod";
 
 import { type framer } from "@/framer";
-import { keyZ as rackKeyZ } from "@/hardware/rack/payload";
+import { ontology } from "@/ontology";
+import { keyZ as rackKeyZ } from "@/rack/payload";
+import { type ranger } from "@/ranger";
+import { status } from "@/status";
 import {
   type Key,
   keyZ,
@@ -31,12 +34,9 @@ import {
   type Status,
   statusZ,
   taskZ,
-} from "@/hardware/task/payload";
-import { type ontology } from "@/ontology";
-import { type ranger } from "@/ranger";
+} from "@/task/payload";
 import { checkForMultipleOrNoResults } from "@/util/retrieve";
 
-export const STATUS_CHANNEL_NAME = "sy_task_status";
 export const COMMAND_CHANNEL_NAME = "sy_task_cmd";
 export const SET_CHANNEL_NAME = "sy_task_set";
 export const DELETE_CHANNEL_NAME = "sy_task_delete";
@@ -172,6 +172,23 @@ export class Task<
     });
   }
 
+  async start(): Promise<void> {
+    await this.executeCommand({ type: "start" });
+  }
+
+  async stop(): Promise<void> {
+    await this.executeCommand({ type: "stop" });
+  }
+
+  async run<T>(fn: () => Promise<T>): Promise<T> {
+    await this.start();
+    try {
+      return await fn();
+    } finally {
+      await this.stop();
+    }
+  }
+
   async snapshottedTo(): Promise<ontology.Resource | null> {
     if (this.ontologyClient == null || this.rangeClient == null)
       throw NOT_CREATED_ERROR;
@@ -189,8 +206,8 @@ const retrieveReqZ = z.object({
   internal: z.boolean().optional(),
   snapshot: z.boolean().optional(),
   searchTerm: z.string().optional(),
-  offset: z.number().optional(),
-  limit: z.number().optional(),
+  offset: z.int().optional(),
+  limit: z.int().optional(),
 });
 
 const singleRetrieveArgsZ = z.union([
@@ -236,11 +253,6 @@ const retrieveResZ = <
 
 export interface RetrieveRequest extends z.infer<typeof retrieveReqZ> {}
 
-const RETRIEVE_ENDPOINT = "/hardware/task/retrieve";
-const CREATE_ENDPOINT = "/hardware/task/create";
-const DELETE_ENDPOINT = "/hardware/task/delete";
-const COPY_ENDPOINT = "/hardware/task/copy";
-
 const createReqZ = <
   Type extends z.ZodLiteral<string> = z.ZodLiteral<string>,
   Config extends z.ZodType = z.ZodType,
@@ -294,7 +306,7 @@ export class Client {
     Config extends z.ZodType = z.ZodType,
     StatusData extends z.ZodType = z.ZodType,
   >(
-    task: New<Type, Config>,
+    task: New<Type, Config, StatusData>,
     schemas: Schemas<Type, Config, StatusData>,
   ): Promise<Task<Type, Config, StatusData>>;
   async create<
@@ -302,7 +314,7 @@ export class Client {
     Config extends z.ZodType = z.ZodType,
     StatusData extends z.ZodType = z.ZodType,
   >(
-    tasks: New<Type, Config>[],
+    tasks: New<Type, Config, StatusData>[],
     schemas: Schemas<Type, Config, StatusData>,
   ): Promise<Task<Type, Config, StatusData>[]>;
 
@@ -311,7 +323,7 @@ export class Client {
     Config extends z.ZodType = z.ZodType,
     StatusData extends z.ZodType = z.ZodType,
   >(
-    task: New<Type, Config> | Array<New<Type, Config>>,
+    task: New<Type, Config, StatusData> | Array<New<Type, Config, StatusData>>,
     schemas?: Schemas<Type, Config, StatusData>,
   ): Promise<Task<Type, Config, StatusData> | Array<Task<Type, Config, StatusData>>> {
     const isSingle = !Array.isArray(task);
@@ -319,7 +331,7 @@ export class Client {
     const createRes = createResZ(schemas);
     const res = await sendRequired(
       this.client,
-      CREATE_ENDPOINT,
+      "/task/create",
       { tasks: array.toArray(task) } as z.infer<typeof createReq>,
       createReq,
       createRes,
@@ -334,7 +346,7 @@ export class Client {
   async delete(keys: Key | Key[]): Promise<void> {
     await sendRequired<typeof deleteReqZ, typeof deleteResZ>(
       this.client,
-      DELETE_ENDPOINT,
+      "/task/delete",
       { keys: array.toArray(keys) },
       deleteReqZ,
       deleteResZ,
@@ -370,7 +382,7 @@ export class Client {
     const isSingle = singleRetrieveArgsZ.safeParse(args).success;
     const res = await sendRequired(
       this.client,
-      RETRIEVE_ENDPOINT,
+      "/task/retrieve",
       args,
       retrieveArgsZ,
       retrieveResZ(schemas),
@@ -385,7 +397,7 @@ export class Client {
     const copyRes = copyResZ();
     const response = await sendRequired(
       this.client,
-      COPY_ENDPOINT,
+      "/task/copy",
       { key, name, snapshot },
       copyReqZ,
       copyRes,
@@ -393,6 +405,12 @@ export class Client {
     return this.sugar(response.task as Payload);
   }
 
+  async list(rack?: number): Promise<Task[]> {
+    const params: RetrieveMultipleParams = { internal: false };
+    if (rack !== undefined) params.rack = rack;
+    return await this.retrieve(params);
+  }
+
   async retrieveSnapshottedTo(taskKey: Key): Promise<ontology.Resource | null> {
     if (this.ontologyClient == null) throw NOT_CREATED_ERROR;
     return await retrieveSnapshottedTo(taskKey, this.ontologyClient);
@@ -459,11 +477,11 @@ export class Client {
   }
 
   async executeCommandSync<StatusData extends z.ZodType = z.ZodType>(
-    parms: ExecuteCommandsSyncParams<StatusData>,
+    params: ExecuteCommandsSyncParams<StatusData>,
   ): Promise<Status<StatusData>[]>;
 
   async executeCommandSync<StatusData extends z.ZodType = z.ZodType>(
-    parms: ExecuteCommandSyncParams<StatusData>,
+    params: ExecuteCommandSyncParams<StatusData>,
   ): Promise<Status<StatusData>>;
 
   async executeCommandSync<StatusData extends z.ZodType = z.ZodType>(
@@ -496,7 +514,10 @@ export class Client {
   }
 }
 
-export const ontologyID = (key: Key): ontology.ID => ({ type: "task", key });
+export const ontologyID = ontology.createIDFactory<Key>("task");
+export const TYPE_ONTOLOGY_ID = ontologyID("");
+
+export const statusKey = (key: Key): string => ontology.idToString(ontologyID(key));
 
 interface ExecuteCommandInternalParams {
   frameClient: framer.Client | null;
@@ -577,7 +598,7 @@ const executeCommandsSync = async <StatusData extends z.ZodType = z.ZodType>({
   name: taskName,
 }: ExecuteCommandsSyncInternalParams<StatusData>): Promise<Status<StatusData>[]> => {
   if (frameClient == null) throw NOT_CREATED_ERROR;
-  const streamer = await frameClient.openStreamer(STATUS_CHANNEL_NAME);
+  const streamer = await frameClient.openStreamer(status.SET_CHANNEL_NAME);
   const cmdKeys = await executeCommands({ frameClient, commands });
   const parsedTimeout = new TimeSpan(timeout);
   let states: Status<StatusData>[] = [];
@@ -593,8 +614,12 @@ const executeCommandsSync = async <StatusData extends z.ZodType = z.ZodType>({
   try {
     while (true) {
       const frame = await Promise.race([streamer.read(), timeoutPromise]);
-      const state = statusZ(statusDataZ).parse(frame.at(-1)[STATUS_CHANNEL_NAME]);
-      if (!cmdKeys.includes(state.key)) continue;
+      const parseResult = statusZ(statusDataZ).safeParse(
+        frame.at(-1)[status.SET_CHANNEL_NAME],
+      );
+      if (!parseResult.success) continue;
+      const state = parseResult.data;
+      if (state.details.cmd == null || !cmdKeys.includes(state.details.cmd)) continue;
       states = [...states.filter((s) => s.key !== state.key), state];
       if (states.length === cmdKeys.length) return states;
     }

package/src/task/external.ts

@@ -0,0 +1,11 @@
+// Copyright 2025 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+export * from "@/task/client";
+export * from "@/task/payload";

package/src/{hardware/task → task}/index.ts

@@ -7,4 +7,4 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
-export * as task from "@/hardware/task/external";
+export * as task from "@/task/external";

package/src/{hardware/task → task}/payload.ts

@@ -10,7 +10,7 @@
 import { binary, type observe, record, status } from "@synnaxlabs/x";
 import { z } from "zod";
 
-import { type Key as RackKey } from "@/hardware/rack/payload";
+import { type Key as RackKey } from "@/rack/payload";
 import { decodeJSONString } from "@/util/decodeJSONString";
 import { parseWithoutKeyConversion } from "@/util/parseWithoutKeyConversion";
 
@@ -22,7 +22,12 @@ export const keyZ = z.union([
 export type Key = z.infer<typeof keyZ>;
 
 export const statusDetailsZ = <DataSchema extends z.ZodType>(data: DataSchema) =>
-  z.object({ task: keyZ, running: z.boolean(), data });
+  z.object({
+    task: keyZ,
+    running: z.boolean(),
+    data,
+    cmd: z.string().optional(),
+  });
 
 export type StatusDetails<DataSchema extends z.ZodType> = z.infer<
   ReturnType<typeof statusDetailsZ<DataSchema>>
@@ -35,6 +40,15 @@ export type Status<StatusData extends z.ZodType = z.ZodUnknown> = z.infer<
   ReturnType<typeof statusZ<StatusData>>
 >;
 
+const newStatusDetailsZ = <DataSchema extends z.ZodType>(data: DataSchema) =>
+  statusDetailsZ(data).partial({ task: true });
+
+export const newStatusZ = <DataSchema extends z.ZodType>(data: DataSchema) =>
+  status.statusZ(newStatusDetailsZ(data)).partial({ key: true, name: true });
+
+export interface NewStatus<DataSchema extends z.ZodType = z.ZodUnknown>
+  extends z.infer<ReturnType<typeof newStatusZ<DataSchema>>> {}
+
 export const taskZ = <
   Type extends z.ZodLiteral<string> = z.ZodLiteral<string>,
   Config extends z.ZodType = z.ZodType,
@@ -88,20 +102,25 @@ export const newZ = <
   schemas?: Schemas<Type, Config, StatusData>,
 ) =>
   taskZ(schemas)
-    .omit({ key: true })
+    .omit({ key: true, status: true })
     .extend({
       key: keyZ.transform((k) => k.toString()).optional(),
       config: z.unknown().transform((c) => binary.JSON_CODEC.encodeString(c)),
+      status: newStatusZ(schemas?.statusDataSchema ?? z.unknown())
+        .optional()
+        .nullable(),
     });
 
 export type New<
   Type extends z.ZodLiteral<string> = z.ZodLiteral<string>,
   Config extends z.ZodType = z.ZodType,
+  StatusData extends z.ZodType = z.ZodUnknown,
 > = {
   key?: Key;
   name: string;
   type: z.infer<Type>;
   config: z.infer<Config>;
+  status?: NewStatus<StatusData>;
 };
 
 export const commandZ = z.object({