Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

new script #18

Open
hbrooks opened this issue Jan 23, 2025 · 2 comments · May be fixed by #19
Open

new script #18

hbrooks opened this issue Jan 23, 2025 · 2 comments · May be fixed by #19

Comments

@hbrooks
Copy link
Member

hbrooks commented Jan 23, 2025

I need help creating a runnable script that showcases a feature within a workflow orchestration system called Hatchet.

My goal is to replace every hardcoded TypeScript code snippet in the Hatchet documentation with a reference to an example script in a public GitHub repository. I need your help, @ellipsis-dev, creating those example scripts.

Please create a script in the src/examples directory of this repo (or a subdirectory, if you choose to create one). This script needs to clearly showcase the feature outlined in the below docs file. You need to:

  1. Create an independently executable script. We want everyone to be able to really simply try out all the awesome features within Hatchet, so make it simple and containing as little code as possible to communicate the feature. To see how other examples files look, see the src/examples directory.

  2. Within the script, enclose the most important code with // ❓ {NAME} before and // ‼️ after. The code between these two comments will be what is shown in the docs - so this section in particular should look very similar to what the actual code snippet looks like. The {NAME} should be replaced with a reasonable name (camelCase) of the example. We'll use this name later on when removing the code snippets

  3. Update package.json to run your new example script! Be sure to follow the format used by the rest of the example: commands.

Here's an example of a well formed script:

import Hatchet from '../sdk';
import { Workflow } from '../workflow';

const hatchet = Hatchet.init();

// ❓ OnFailure Step
// This workflow will fail because the step will throw an error
// we define an onFailure step to handle this case

const workflow: Workflow = {
  // ... normal workflow definition
  id: 'on-failure-example',
  description: 'test',
  on: {
    event: 'user:create',
  },
  // ,
  steps: [
    {
      name: 'step1',
      run: async (ctx) => {
        // 👀 this step will always throw an error
        throw new Error('Step 1 failed');
      },
    },
  ],
  // 👀 After the workflow fails, this special step will run
  onFailure: {
    name: 'on-failure-step',
    run: async (ctx) => {
      // 👀 we can do things like perform cleanup logic
      // or notify a user here

      // 👀 you can access the error from the failed step(s) like this
      console.log(ctx.stepRunErrors());

      return { onFailure: 'step' };
    },
  },
};
// ‼️

// ❓ OnFailure With Details
// Coming soon to TypeScript! https://github.com/hatchet-dev/hatchet-typescript/issues/447
// ‼️

async function main() {
  const worker = await hatchet.worker('example-worker', 1);
  await worker.registerWorkflow(workflow);
  worker.start();
}

main();

This example contains two TypeScript code snippets that are referenced in the docs. Only 1 is implemented, but you get the idea.

Later, I'll go through the docs script and replace the hardcoded TypeScript code snippets with a reference to your new script.

Okay, ready to create a new executable example script? Let's do it! 🚀 Here is the docs file we're currently updating, it's file path is frontend/docs/pages/home/features/webhooks.mdx and the contents of the file are:


import { Callout } from "nextra/components";

Webhooks

In order to run workflows in serverless environments like AWS Lambda, Vercel, GCP Cloud Functions, and CloudFlare Workers, you can use webhooks.

Webhooks currently have first-class support only in the Typescript and Go SDKs.

If you are using the following tools, we have quickstart repositories to help you get started:

Creating a Webhook

Navigate to resources > Workers > Webhook Workers and click "Create Webhook Endpoint". You can then enter a name and the URL where your webhook will live.

Create Webhook

For example, provide the following details:

  • Name: My Webhook App
  • URL: https://example.com/api/webhook

Next, click "Create". You will then be shown the webhook secret which you need to provide as an environment variable to your app.

Webhook Secret

The secret is only shown once and cannot be retrieved afterwards.

Next, you have to set up your code to handle the webhooks at the specified URL.

Setting up your code

This guide assumes the webhook URL path is /api/webhook.

You will need to set up two environment variables:

  • HATCHET_WEBHOOK_SECRET: The webhook secret you created earlier
  • HATCHET_CLIENT_TOKEN: The Hatchet API token

Next.js App Dir

import { Hatchet } from "@hatchet-dev/typescript-sdk";

const hatchet = Hatchet.init();

const webhooks = hatchet.webhooks([workflow]);

export const { GET, POST, PUT } = webhooks.nextJSHandler({
  secret: process.env.HATCHET_WEBHOOK_SECRET,
});

Next.js Pages Dir

import { Hatchet } from "@hatchet-dev/typescript-sdk";

export const maxDuration = 60; // add this on vercel: 60 for free plans, 300 for pro plans

const hatchet = Hatchet.init();

const webhooks = hatchet.webhooks([workflow]);

export const { GET, POST, PUT } = webhooks.nextJSHandler({
  secret: process.env.HATCHET_WEBHOOK_SECRET || "",
});

Express.js App

import express from "express";
import { Hatchet } from "@hatchet-dev/typescript-sdk";

export const maxDuration = 60; // add this on vercel: 60 for free plans, 300 for pro plans

const hatchet = Hatchet.init();

const webhooks = hatchet.webhooks([workflow]);

const app = express();

app.use(
  "/api/webhook",
  webhooks.expressHandler({ secret: process.env.HATCHET_WEBHOOK_SECRET }),
);

app.listen(8080, () => {
  console.log("Server is listening on port 8080");
});

Node.js standard http server

import { createServer } from "http";
import { Hatchet } from "@hatchet-dev/typescript-sdk";

const hatchet = Hatchet.init();

const webhooks = hatchet.webhooks([workflow]);

const server = createServer(
  webhooks.httpHandler({ secret: process.env.HATCHET_WEBHOOK_SECRET }),
);

server.listen(8080, () => {
  console.log("Server is listening on port 8080");
});
@hbrooks
Copy link
Member Author

hbrooks commented Jan 23, 2025

@ellipsis-dev create a PR

Copy link

ellipsis-dev bot commented Jan 23, 2025

Pull request created: #19

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

1 participant