@rstreamlabs/tunnels 3.0.0 → 3.2.0

package/README.md

@@ -172,8 +172,9 @@ credentials are additionally capped by the PAT expiration.
 
 ## Webhooks
 
-Validate signed engine webhook payloads with constant-time signature comparison
-and schema parsing:
+Validate signed webhook payloads with constant-time signature comparison and
+schema parsing. Webhook parsing accepts lifecycle events only; stream summaries
+and connection logs use the separate project log event schema.
 
 ```ts
 const event = await client.webhooks.event(
@@ -185,6 +186,57 @@ const event = await client.webhooks.event(
 console.log(event.type);
 ```
 
+For a receiving backend, verify the signature before touching the JSON payload
+and use the event id as the idempotency key.
+
+```ts
+import { RstreamWebhookResource, type WebhookEvent } from "@rstreamlabs/tunnels";
+
+const webhooks = new RstreamWebhookResource();
+
+declare function markOnline(
+  eventId: string,
+  resourceId: string,
+  labels: Record<string, string>,
+): Promise<void>;
+
+declare function markOffline(
+  eventId: string,
+  resourceId: string,
+  labels: Record<string, string>,
+): Promise<void>;
+
+async function handleLifecycleEvent(
+  event: WebhookEvent & { id: string },
+): Promise<void> {
+  switch (event.type) {
+    case "client.created":
+    case "tunnel.created":
+      await markOnline(event.id, event.object.id, event.object.labels ?? {});
+      return;
+    case "client.deleted":
+    case "tunnel.deleted":
+      await markOffline(event.id, event.object.id, event.object.labels ?? {});
+      return;
+  }
+}
+
+export async function receiveWebhook(request: Request) {
+  const rawBody = Buffer.from(await request.arrayBuffer());
+  const signature = request.headers.get("rstream-signature");
+  if (!signature) throw new Error("Missing webhook signature.");
+
+  const event = await webhooks.event(
+    rawBody,
+    signature,
+    process.env.WEBHOOK_SECRET!,
+  );
+  if (!event.id) throw new Error("Missing webhook event id.");
+
+  await handleLifecycleEvent(event);
+}
+```
+
 ## WebTTY Helpers
 
 Use `parseWebTTYServers()` to derive WebTTY server metadata from tunnel
@@ -196,6 +248,10 @@ import { parseWebTTYServers } from "@rstreamlabs/tunnels";
 const servers = parseWebTTYServers(await client.tunnels.list());
 ```
 
+WebTTY server metadata includes advertised capabilities such as `exec` and
+`fs`. Older servers that do not advertise capabilities are treated as
+`exec`-only with the execution path `/`.
+
 ## OpenAPI Document
 
 The package exports the Engine API OpenAPI document from the main entrypoint

package/dist/{chunk-UUZYVELQ.mjs → chunk-VUAM3LRU.mjs}

@@ -324,15 +324,23 @@ var commonEventsSchema = [
     object: tunnelSchema2
   })
 ];
+var webhookDeliverableEventsSchema = [
+  commonEventsSchema[0],
+  commonEventsSchema[2],
+  commonEventsSchema[3],
+  commonEventsSchema[5]
+];
 var wsEventsSchema = z4.union([
   stateInitialEventSchema,
   ...commonEventsSchema
 ]);
-var webhookEventsSchema = z4.union([
-  ...commonEventsSchema,
-  streamSummaryEventSchema
+var webhookEventsSchema = z4.union(webhookDeliverableEventsSchema);
+var projectLogEventsSchema = streamSummaryEventSchema;
+var eventSchema = z4.union([
+  wsEventsSchema,
+  webhookEventsSchema,
+  projectLogEventsSchema
 ]);
-var eventSchema = z4.union([wsEventsSchema, webhookEventsSchema]);
 
 // src/openapi.ts
 import * as z5 from "zod";
@@ -688,8 +696,10 @@ export {
   streamTLSInfoSchema,
   streamEndpointSchema,
   streamSummarySchema,
+  streamSummaryEventSchema,
   wsEventsSchema,
   webhookEventsSchema,
+  projectLogEventsSchema,
   eventSchema,
   tunnelFilterSchema,
   listTunnelsParamsSchema,