Generate the webhook route in the static builder (#67)

Author: pranaygp

.changeset/light-rice-rush.md

@@ -0,0 +1,5 @@
+---
+"@workflow/cli": patch
+---
+
+Generate the webhook route in the static builder mode

packages/cli/src/lib/builders/vercel-static.ts

@@ -14,6 +14,7 @@ export class VercelStaticBuilder extends BaseBuilder {
     };
     await this.buildStepsBundle(options);
     await this.buildWorkflowsBundle(options);
+    await this.buildWebhookFunction();
 
     await this.buildClientLibrary();
   }
@@ -77,4 +78,23 @@ export class VercelStaticBuilder extends BaseBuilder {
       tsPaths,
     });
   }
+
+  private async buildWebhookFunction(): Promise<void> {
+    console.log(
+      'Creating vercel API webhook bundle at',
+      this.config.webhookBundlePath
+    );
+
+    const webhookBundlePath = resolve(
+      this.config.workingDir,
+      this.config.webhookBundlePath
+    );
+
+    // Ensure directory exists
+    await mkdir(dirname(webhookBundlePath), { recursive: true });
+
+    await this.createWebhookBundle({
+      outfile: webhookBundlePath,
+    });
+  }
 }

packages/cli/src/lib/builders/webhook-route.test.ts

@@ -28,6 +28,7 @@ describe('Webhook route generation', () => {
         workingDir: testDir,
         stepsBundlePath: '',
         workflowsBundlePath: '',
+        webhookBundlePath: '',
         watch: false,
         externalPackages: [],
       };
@@ -72,6 +73,7 @@ describe('Webhook route generation', () => {
         workingDir: testDir,
         stepsBundlePath: '',
         workflowsBundlePath: '',
+        webhookBundlePath: '',
         watch: false,
         externalPackages: [],
       };
@@ -104,6 +106,7 @@ describe('Webhook route generation', () => {
         workingDir: testDir,
         stepsBundlePath: '',
         workflowsBundlePath: '',
+        webhookBundlePath: '',
         watch: false,
         externalPackages: [],
       };
@@ -137,6 +140,7 @@ describe('Webhook route generation', () => {
         workingDir: testDir,
         stepsBundlePath: '',
         workflowsBundlePath: '',
+        webhookBundlePath: '',
         watch: false,
         externalPackages: [],
       };
@@ -176,6 +180,7 @@ describe('Webhook route generation', () => {
         workingDir: testDir,
         stepsBundlePath: '',
         workflowsBundlePath: '',
+        webhookBundlePath: '',
         watch: false,
         externalPackages: [],
       };
@@ -217,6 +222,7 @@ describe('Webhook route generation', () => {
         workingDir: testDir,
         stepsBundlePath: '',
         workflowsBundlePath: '',
+        webhookBundlePath: '',
         watch: false,
         externalPackages: [],
       };
@@ -254,6 +260,7 @@ describe('Webhook route generation', () => {
         workingDir: testDir,
         stepsBundlePath: '',
         workflowsBundlePath: '',
+        webhookBundlePath: '',
         watch: false,
         externalPackages: [],
       };

packages/cli/src/lib/config/types.ts

@@ -26,6 +26,7 @@ export interface WorkflowConfig {
   buildTarget: BuildTarget;
   stepsBundlePath: string;
   workflowsBundlePath: string;
+  webhookBundlePath: string;
 
   // Optionally generate a client library for workflow execution. The preferred
   // method of using workflow is to use a loader within a framework (like

packages/cli/src/lib/config/workflow-config.ts

@@ -17,6 +17,7 @@ export const getWorkflowConfig = (
     buildTarget: buildTarget as BuildTarget,
     stepsBundlePath: './.well-known/workflow/v1/step.js',
     workflowsBundlePath: './.well-known/workflow/v1/flow.js',
+    webhookBundlePath: './.well-known/workflow/v1/webhook.js',
     workflowManifestPath: workflowManifest,
 
     // WIP: generate a client library to easily execute workflows/steps

packages/next/src/index.ts

@@ -90,8 +90,9 @@ export function withWorkflow({
         dirs: ['pages', 'app', 'src/pages', 'src/app'],
         workingDir: process.cwd(),
         buildTarget: 'next',
-        workflowsBundlePath: '',
-        stepsBundlePath: '',
+        workflowsBundlePath: '', // not used in base
+        stepsBundlePath: '', // not used in base
+        webhookBundlePath: '', // node used in base
         externalPackages: [
           ...require('next/dist/lib/server-external-packages.json'),
           ...(nextConfig.serverExternalPackages || []),

packages/nitro/src/builders.ts

@@ -9,6 +9,7 @@ const CommonBuildOptions = {
   buildTarget: 'next' as const, // unused in base
   stepsBundlePath: '', // unused in base
   workflowsBundlePath: '', // unused in base
+  webhookBundlePath: '', // unused in base
 };
 
 export class VercelBuilder extends VercelBuildOutputAPIBuilder {

packages/swc-plugin-workflow/spec.md

@@ -6,7 +6,7 @@ The swc plugin has 3 modes - 'step' mode, 'workflow' mode, and 'client' mode
 
 ## Step Mode
 
-When executed in 'step' mode, step definitions is kept as is and are simply registered using `registerStepFunction` from `@workflow/core/private`. The directives are removed. For example:
+When executed in 'step' mode, step definitions is kept as is and are simply registered using `registerStepFunction` from `workflow/internal/private`. The directives are removed. For example:
 
 Input code:
 
@@ -20,14 +20,18 @@ export async function add(a, b) {
 Output code
 
 ```
-import { registerStepFunction } from "@workflow/core/private"
+import { registerStepFunction } from "workflow/internal/private"
 
 export async function add(a, b) {
   return a + b
 }
-registerStepFunction(add)
+registerStepFunction("step//input.js//add", add)
 ```
 
+**ID Generation:** Step IDs are generated using the format `step//{filepath}//{functionName}`, where:
+- `filepath` is the relative path to the file from the project root
+- `functionName` is the name of the step function
+
 Workflow definitions are left untouched in step mode, including leaving the directives intact.
 
 Upstream, a bundler will use this plugin in step mode to create a server bundle of multiple steps and serve it via an API endpoint at `.well-known/workflow/v1/step`
@@ -49,11 +53,13 @@ Output code
 
 ```
 export async function add(a, b) {
-  return globalThis[Symbol.for("WORKFLOW_USE_STEP")]("add")(a, b);
+  return globalThis[Symbol.for("WORKFLOW_USE_STEP")]("step//input.js//add")(a, b);
 }
 ```
 
-Workflow definitions are left untouched in workflow mode, aside from the directive itself being removed.
+**ID Generation:** The same step ID format `step//{filepath}//{functionName}` is used when replacing step function bodies.
+
+Workflow definitions are left untouched in workflow mode, aside from the directive itself being removed and a `workflowId` property being attached.
 
 Input code
 
@@ -70,13 +76,16 @@ Output code
 export async function example(a, b) {
   return a + b;
 }
+example.workflowId = "workflow//input.js//example";
 ```
 
+**ID Generation:** Workflow IDs are generated using the format `workflow//{filepath}//{functionName}` and attached as a property to the function.
+
 Upstream, a bundler will use this plugin in workflow mode to create a server bundle of all the workflows and serve it via an API endpoint at `.well-known/workflow/v1/flow`. The workflow endpoint handler encapsulates logic to execute the correct workflow using the function name, which is why nothing needs to be done to the workflows themselves. They just need to be exported.
 
 ## Client Mode
 
-When executed in 'client' mode, step and workflow definitions have their bodies replaced with a call to `runStep` and `start` respectively. Both these helper functions are exported from the `@workflow/core` package. They effectively proxy the requests to execute steps and workflows on the server (using the bundles created in the other two modes).
+When executed in 'client' mode, step and workflow definitions have their bodies replaced with a call to `runStep` and throw statements respectively. `runStep` is exported from `workflow/api`. It effectively proxies the requests to execute steps on the server (using the bundles created in the other modes).
 
 Input code
 
@@ -97,18 +106,23 @@ Output code
 
 ```
 // workflow/main.js
-import { start as __private_workflow_start, runStep as __private_run_step } from "@workflow/core/runtime"
+import { runStep as __private_run_step } from "workflow/api"
 
 export async function add(a, b) {
   return __private_run_step('add', { arguments: [a, b] })
 }
 
 export async function workflow(a, b) {
-  return __private_workflow_start('workflow', [a, b])
+  throw new Error("You attempted to execute workflow workflow function directly. To start a workflow, use start(workflow) from workflow");
 }
+workflow.workflowId = "workflow//workflow/main.js//workflow";
 ```
 
-Upstream, this mode is typically used by a framework loader (like a NextJS/webpack loader) to JIT transform workflow executions into proxied start calls.
+**ID Generation:**
+- Step functions use `runStep` with the function name (not the full ID)
+- Workflow functions throw an error if called directly and have the `workflowId` property attached using the format `workflow//{filepath}//{functionName}`
+
+Upstream, this mode is typically used by a framework loader (like a Next.js/webpack loader) to JIT transform workflow executions into proxied calls.
 
 ## Notes