@sealant/api-contracts-next 0.40.0-next.756 → 0.40.0-next.758

package/dist/core-api/workspace-forward.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The workspace forward's v2 wire contract: `GET /v1/workspaces/:workspaceId/forward/v2` with the
+ * subprotocol {@link FORWARD_V2_SUBPROTOCOL}. A WHATWG `WebSocket` cannot read the status of a
+ * refused upgrade, so v2 accepts the upgrade first and answers with one text frame: `ready`, after
+ * which binary frames carry payload both ways, or `refused`, after which the server closes with
+ * {@link FORWARD_REFUSED_CLOSE_CODE}. A request without an upgrade gets 426 and is never dialled.
+ */
+import { Schema } from "effect";
+export declare const FORWARD_V2_SUBPROTOCOL = "sealant.forward.v2";
+/** The largest binary frame either side may send. */
+export declare const FORWARD_V2_MAX_FRAME_BYTES: number;
+/** Ends the socket after a `refused` frame. It says nothing about why: the frame's reason does. */
+export declare const FORWARD_REFUSED_CLOSE_CODE = 4400;
+export declare const forwardRefusalReasonSchema: Schema.Literals<readonly ["workspace-not-ready", "runtime-unreachable", "runtime-untargetable", "connection-refused", "name-unresolved", "network-unreachable", "dial-timeout", "dial-failed", "not-found", "unauthorized", "forbidden", "budget-exceeded", "invalid-target", "owner-required", "internal", "owner-exited", "peer-mismatch", "binding-unverifiable", "binding-unsupported"]>;
+export type ForwardRefusalReason = typeof forwardRefusalReasonSchema.Type;
+/** The HTTP status each refusal would have had before the upgrade. Callers branch on the reason. */
+export declare const FORWARD_REFUSAL_STATUS: {
+    readonly "workspace-not-ready": 409;
+    readonly "runtime-unreachable": 503;
+    readonly "runtime-untargetable": 503;
+    readonly "connection-refused": 502;
+    readonly "name-unresolved": 502;
+    readonly "network-unreachable": 502;
+    readonly "dial-timeout": 504;
+    readonly "dial-failed": 502;
+    readonly "not-found": 404;
+    readonly unauthorized: 401;
+    readonly forbidden: 403;
+    readonly "budget-exceeded": 429;
+    readonly "invalid-target": 400;
+    readonly "owner-required": 400;
+    readonly internal: 500;
+    readonly "owner-exited": 409;
+    readonly "peer-mismatch": 409;
+    readonly "binding-unverifiable": 409;
+    readonly "binding-unsupported": 409;
+};
+export declare const forwardBindingSchema: Schema.Struct<{
+    readonly kind: Schema.Literal<"port">;
+}>;
+export type ForwardBinding = typeof forwardBindingSchema.Type;
+export declare const forwardReadyFrameSchema: Schema.Struct<{
+    readonly t: Schema.Literal<"ready">;
+    readonly version: Schema.Literal<2>;
+    readonly binding: Schema.Struct<{
+        readonly kind: Schema.Literal<"port">;
+    }>;
+}>;
+export type ForwardReadyFrame = typeof forwardReadyFrameSchema.Type;
+/**
+ * Decoded with any `reason`, so a client keeps a refusal from a Core newer than itself, with the
+ * status and message that Core sent.
+ */
+export declare const forwardRefusedFrameSchema: Schema.Struct<{
+    readonly t: Schema.Literal<"refused">;
+    readonly reason: Schema.String;
+    readonly message: Schema.String;
+    readonly status: Schema.Int;
+}>;
+export type ForwardRefusedFrame = typeof forwardRefusedFrameSchema.Type;
+export declare const forwardRefusedFrame: (reason: "binding-unsupported" | "binding-unverifiable" | "budget-exceeded" | "connection-refused" | "dial-failed" | "dial-timeout" | "forbidden" | "internal" | "invalid-target" | "name-unresolved" | "network-unreachable" | "not-found" | "owner-exited" | "owner-required" | "peer-mismatch" | "runtime-unreachable" | "runtime-untargetable" | "unauthorized" | "workspace-not-ready", message: string) => {
+    readonly t: "refused";
+    readonly reason: string;
+    readonly message: string;
+    readonly status: number;
+};
+/** The first frame the server sends on a v2 forward, as JSON text. */
+export declare const forwardOpenFrameSchema: Schema.Union<readonly [Schema.Struct<{
+    readonly t: Schema.Literal<"ready">;
+    readonly version: Schema.Literal<2>;
+    readonly binding: Schema.Struct<{
+        readonly kind: Schema.Literal<"port">;
+    }>;
+}>, Schema.Struct<{
+    readonly t: Schema.Literal<"refused">;
+    readonly reason: Schema.String;
+    readonly message: Schema.String;
+    readonly status: Schema.Int;
+}>]>;
+export type ForwardOpenFrame = typeof forwardOpenFrameSchema.Type;

package/dist/core-api/workspace-forward.js

@@ -0,0 +1,83 @@
+/**
+ * The workspace forward's v2 wire contract: `GET /v1/workspaces/:workspaceId/forward/v2` with the
+ * subprotocol {@link FORWARD_V2_SUBPROTOCOL}. A WHATWG `WebSocket` cannot read the status of a
+ * refused upgrade, so v2 accepts the upgrade first and answers with one text frame: `ready`, after
+ * which binary frames carry payload both ways, or `refused`, after which the server closes with
+ * {@link FORWARD_REFUSED_CLOSE_CODE}. A request without an upgrade gets 426 and is never dialled.
+ */
+import { Schema } from "effect";
+export const FORWARD_V2_SUBPROTOCOL = "sealant.forward.v2";
+/** The largest binary frame either side may send. */
+export const FORWARD_V2_MAX_FRAME_BYTES = 64 * 1024;
+/** Ends the socket after a `refused` frame. It says nothing about why: the frame's reason does. */
+export const FORWARD_REFUSED_CLOSE_CODE = 4400;
+export const forwardRefusalReasonSchema = Schema.Literals([
+    "workspace-not-ready",
+    "runtime-unreachable",
+    "runtime-untargetable",
+    "connection-refused",
+    "name-unresolved",
+    "network-unreachable",
+    "dial-timeout",
+    "dial-failed",
+    "not-found",
+    "unauthorized",
+    "forbidden",
+    "budget-exceeded",
+    "invalid-target",
+    "owner-required",
+    "internal",
+    "owner-exited",
+    "peer-mismatch",
+    "binding-unverifiable",
+    "binding-unsupported",
+]);
+/** The HTTP status each refusal would have had before the upgrade. Callers branch on the reason. */
+export const FORWARD_REFUSAL_STATUS = {
+    "workspace-not-ready": 409,
+    "runtime-unreachable": 503,
+    "runtime-untargetable": 503,
+    "connection-refused": 502,
+    "name-unresolved": 502,
+    "network-unreachable": 502,
+    "dial-timeout": 504,
+    "dial-failed": 502,
+    "not-found": 404,
+    unauthorized: 401,
+    forbidden: 403,
+    "budget-exceeded": 429,
+    "invalid-target": 400,
+    "owner-required": 400,
+    internal: 500,
+    "owner-exited": 409,
+    "peer-mismatch": 409,
+    "binding-unverifiable": 409,
+    "binding-unsupported": 409,
+};
+export const forwardBindingSchema = Schema.Struct({ kind: Schema.Literal("port") });
+export const forwardReadyFrameSchema = Schema.Struct({
+    t: Schema.Literal("ready"),
+    version: Schema.Literal(2),
+    binding: forwardBindingSchema,
+});
+/**
+ * Decoded with any `reason`, so a client keeps a refusal from a Core newer than itself, with the
+ * status and message that Core sent.
+ */
+export const forwardRefusedFrameSchema = Schema.Struct({
+    t: Schema.Literal("refused"),
+    reason: Schema.String,
+    message: Schema.String,
+    status: Schema.Int,
+});
+export const forwardRefusedFrame = (reason, message) => ({
+    t: "refused",
+    reason,
+    message,
+    status: FORWARD_REFUSAL_STATUS[reason],
+});
+/** The first frame the server sends on a v2 forward, as JSON text. */
+export const forwardOpenFrameSchema = Schema.Union([
+    forwardReadyFrameSchema,
+    forwardRefusedFrameSchema,
+]);

package/dist/index.d.ts

@@ -13,6 +13,7 @@ export * from "./core-api/request-refusal.js";
 export * from "./core-api/sessions.js";
 export * from "./core-api/access-tokens.js";
 export * from "./core-api/workspaces.js";
+export * from "./core-api/workspace-forward.js";
 export * from "./core-api/ssh-keys.js";
 export * from "./core-api/system.js";
 export * from "./core-api/users.js";

package/dist/index.js

@@ -13,6 +13,7 @@ export * from "./core-api/request-refusal.js";
 export * from "./core-api/sessions.js";
 export * from "./core-api/access-tokens.js";
 export * from "./core-api/workspaces.js";
+export * from "./core-api/workspace-forward.js";
 export * from "./core-api/ssh-keys.js";
 export * from "./core-api/system.js";
 export * from "./core-api/users.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sealant/api-contracts-next",
-  "version": "0.40.0-next.756",
+  "version": "0.40.0-next.758",
   "description": "Contract-first HTTP API definitions for Sealant services",
   "license": "Apache-2.0",
   "repository": {
@@ -36,7 +36,7 @@
   "peerDependencies": {
     "effect": "^4.0.5"
   },
-  "gitHead": "93701b91347c5f4bc66573a0ee4e74073b68c83f",
+  "gitHead": "cad5836dece75c30a8aa91978d233cd1c1f7064d",
   "publishConfig": {
     "access": "public"
   }