@akterjs/client 0.1.2 → 0.1.4

package/README.md

@@ -14,5 +14,7 @@ An actor whose contract declares `files: Akter.fileAccess({ callers })` has file
 
 `@akterjs/client/operations` is the actor half of the operation registry that drives the `akter` CLI and the hosted MCP server (the Cloud half is `@akterjs/cloud-api/operations`): `actorOperations` lists each exposed kind (`call`, `query`, `state`, `watch`, `create`, `ensure`, `fork`, and the file kinds `files/list`, `files/usage`, `files/download` and `files/upload`, whose three session RPCs are one kind) with its command, tool name, input schema and annotations, `kindsOf` gives every RPC of an actor's group its kind or none, so a new kind of RPC fails the coverage test until it has an operation, and `actorRequestOf` builds the RPC tag and payload a caller sends, minting a UUIDv7 command id when the kind takes one and none was given. `@akterjs/client/actor-rpc` holds the one-RPC unary and streaming clients those requests go through, with schema-free JSON payloads, and the file transfers both callers run: `uploadSession({ request, content, wait })` opens an upload, appends the bytes in chunks of at most 1 MiB at their offsets and closes it for the receipt, and `downloadChunks({ request, wait })` collects a download's base64 chunks, failing whole rather than returning part of a file.
 
+`@akterjs/client/cloud-pending` is the Cloud half's one reply both callers ask again on: `isStillRunning({ status, body })` says whether a Cloud API answer is the 503 "still running, ask again with the same id" that a fork past the API's 30 second deadline gets, and `askAgainSchedule` is how they ask, 1, 2 and 4 seconds apart and then every 5, for about 5 minutes.
+
 - Depends on: `@akterjs/effect` (peer, contracts only) and `effect` (peer). `@akterjs/effect` is a peer so the app and the client share one copy: the client decodes errors into its classes, and a second copy would break `instanceof` on them.
 - Must not depend on: any private package.

package/dist/actor-operations.pure.mjs

@@ -151,7 +151,7 @@ const declared = [
 		readOnly: true
 	},
 	{
-		description: "Copy one file (at most 1 MiB) between an actor and its computer. fromComputer returns a receipt; attach it with an actor command.",
+		description: "Copy one file between an actor and its computer. fromComputer returns a receipt; attach it with an actor command.",
 		fields: [
 			"actor",
 			"key",

package/dist/cloud/cloud-pending.pure.d.mts

@@ -0,0 +1,16 @@
+import { Schedule } from "effect";
+interface Answered {
+  readonly body: unknown;
+  readonly status: number;
+}
+/** Whether an answer is the Cloud API's documented "still running, ask again with the same id". */
+declare const isStillRunning: ({ body, status }: Answered) => boolean;
+/** How long a caller keeps asking again before it gives the 503 back as the answer. */
+declare const stillRunningWait = "5 minutes";
+/**
+ * How a caller asks again while an operation is still running: 1, 2 and 4 seconds apart, then every 5, for about
+ * five minutes. Each ask is held by the Cloud API for up to its 30 s deadline, so the waits only keep a fast refusal
+ * from becoming a tight loop.
+ */
+declare const askAgainSchedule: Schedule.Schedule<import("effect/Duration").Duration, unknown, never, never>;
+export { askAgainSchedule, isStillRunning, stillRunningWait };

package/dist/cloud/cloud-pending.pure.mjs

@@ -0,0 +1,21 @@
+import { Schedule, Schema } from "effect";
+// src/cloud/cloud-pending.pure.ts
+/**
+* The Cloud API answers an operation that outlasts its 30 s deadline, such as a fork that copies computers, with 503
+* ActorUnavailableError and a reason saying it is still running and to ask again with the same id, which answers it and
+* never does the work twice (akter-cloud's actorForks.create). Anything else a 503 says, such as a lost reply or a fork
+* that didn't finish, is an error: only this reason means that asking again, unchanged, is the way to the answer.
+*/
+const unavailable = 503;
+const StillRunning = Schema.TaggedStruct("ActorUnavailableError", { reason: Schema.String.check(Schema.isPattern(/\bis still running\b.*\bask again with the same \w+ id\b/iu)) });
+/** Whether an answer is the Cloud API's documented "still running, ask again with the same id". */
+const isStillRunning = ({ body, status }) => status === unavailable && Schema.is(StillRunning)(body);
+/** How long a caller keeps asking again before it gives the 503 back as the answer. */
+const stillRunningWait = "5 minutes";
+/**
+* How a caller asks again while an operation is still running: 1, 2 and 4 seconds apart, then every 5, for about
+* five minutes. Each ask is held by the Cloud API for up to its 30 s deadline, so the waits only keep a fast refusal
+* from becoming a tight loop.
+*/
+const askAgainSchedule = Schedule.max([Schedule.min([Schedule.exponential("1 second"), Schedule.spaced("5 seconds")]), Schedule.during(stillRunningWait)]);
+export { askAgainSchedule, isStillRunning, stillRunningWait };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akterjs/client",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Effect and Promise clients for calling Akter actors from Bun, Node, Workers and browsers.",
   "license": "Apache-2.0",
   "repository": {
@@ -34,6 +34,10 @@
     "./actor-rpc": {
       "types": "./dist/actor-rpc.pure.d.mts",
       "default": "./dist/actor-rpc.pure.mjs"
+    },
+    "./cloud-pending": {
+      "types": "./dist/cloud/cloud-pending.pure.d.mts",
+      "default": "./dist/cloud/cloud-pending.pure.mjs"
     }
   },
   "publishConfig": {
@@ -41,7 +45,7 @@
     "provenance": true
   },
   "devDependencies": {
-    "@akterjs/effect": "0.1.2",
+    "@akterjs/effect": "0.1.4",
     "@akterjs/workerd-test": "0.0.0",
     "@effect/platform-node": "4.1.2",
     "@effect/vitest": "4.1.2",
@@ -55,7 +59,7 @@
     "vitest": "5.1.0"
   },
   "peerDependencies": {
-    "@akterjs/effect": "0.1.2",
+    "@akterjs/effect": "0.1.4",
     "effect": "4.1.2"
   },
   "scripts": {

package/src/actor-operations.pure.ts

@@ -171,7 +171,7 @@ const declared: readonly Declared[] = [
   },
   {
     description:
-      "Copy one file (at most 1 MiB) between an actor and its computer. fromComputer returns a receipt; attach it with an actor command.",
+      "Copy one file between an actor and its computer. fromComputer returns a receipt; attach it with an actor command.",
     fields: ["actor", "key", "computer", "direction", "path", "computerPath"],
     flag: "computerFiles",
     idempotent: false,

package/src/cloud/cloud-pending.pure.ts

@@ -0,0 +1,36 @@
+import { Schedule, Schema } from "effect";
+
+/**
+ * The Cloud API answers an operation that outlasts its 30 s deadline, such as a fork that copies computers, with 503
+ * ActorUnavailableError and a reason saying it is still running and to ask again with the same id, which answers it and
+ * never does the work twice (akter-cloud's actorForks.create). Anything else a 503 says, such as a lost reply or a fork
+ * that didn't finish, is an error: only this reason means that asking again, unchanged, is the way to the answer.
+ */
+const unavailable = 503;
+
+const StillRunning = Schema.TaggedStruct("ActorUnavailableError", {
+  reason: Schema.String.check(Schema.isPattern(/\bis still running\b.*\bask again with the same \w+ id\b/iu)),
+});
+
+interface Answered {
+  readonly body: unknown;
+  readonly status: number;
+}
+
+/** Whether an answer is the Cloud API's documented "still running, ask again with the same id". */
+const isStillRunning = ({ body, status }: Answered): boolean => status === unavailable && Schema.is(StillRunning)(body);
+
+/** How long a caller keeps asking again before it gives the 503 back as the answer. */
+const stillRunningWait = "5 minutes";
+
+/**
+ * How a caller asks again while an operation is still running: 1, 2 and 4 seconds apart, then every 5, for about
+ * five minutes. Each ask is held by the Cloud API for up to its 30 s deadline, so the waits only keep a fast refusal
+ * from becoming a tight loop.
+ */
+const askAgainSchedule = Schedule.max([
+  Schedule.min([Schedule.exponential("1 second"), Schedule.spaced("5 seconds")]),
+  Schedule.during(stillRunningWait),
+]);
+
+export { askAgainSchedule, isStillRunning, stillRunningWait };