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

Add tools.sendEvent() to step function tooling #75

Closed
wants to merge 41 commits into from

Conversation

jpwilliams
Copy link
Member

Summary

Adds a new tool, sendEvent(), used to send events from a step function reliably. Without this, inngest.send() will repeatedly send events during step function executions, sending many more events than anticipated.

Todo

  • Executor changes to send event upon receipt with an idempotency ID of the run ID and hash of the step.

Related

We were previously throwing the serialization error here accidentally.
It now includes an order and the progress through the stack so that the
SDK can decide how much it wants to use.
@tonyhb
Copy link
Contributor

tonyhb commented Jan 15, 2023

This is a great idea! I'm stealing your feedback now - should we also let users do inngest.send() and handle this under the hood?

Is it possible to make function state accessible to the inngest client (moving away from stateless funcs -> inngest.createFunction), and then inngest.send auto-detected function state and ran through the same logic as tools.send?

I'm not sure if this is possible but it'd be good to try and remove that footgun? 🤔

Part of me thinks that this year we might need our own linting rules to help with this stuff too haha.

@jpwilliams
Copy link
Member Author

jpwilliams commented Jan 15, 2023

This is a great idea! I'm stealing your feedback now - should we also let users do inngest.send() and handle this under the hood?

Is it possible to make function state accessible to the inngest client (moving away from stateless funcs -> inngest.createFunction), and then inngest.send auto-detected function state and ran through the same logic as tools.send?

I'm not sure if this is possible but it'd be good to try and remove that footgun? 🤔

@tonyhb A great idea! Yeah, I think that - as we lean on serverless - if a function is being executed then we can safely assume that the attached client should detect this state and silently use tools.send.

The only danger comes if we're running serverful and the same client might be running concurrent executions; in this case we lose the ability to understand which execution we should use the tool from.

To solve that, we'd need the client to be able to understand the current context across async functions. Node’s async context tracking (async_hooks) can provide some value here, though implementation differs between environments; Deno has a polyfilled version that serves no purpose, and v8 worker environments (like Cloudflare) only offer some of the features. It's not something we can support everywhere, but this is also not a current concern.


Part of me thinks that this year we might need our own linting rules to help with this stuff too haha.

Yes! 🙌 It can help folks a tonne with the small amount of gotchas with the tooling, e.g. affecting out-of-scope variables in tools.run.

Definitely want to hack on this (and an extension to bundle it) when I have time!

@jpwilliams jpwilliams force-pushed the async-await-parallel-steps branch 4 times, most recently from e242f29 to eff8f4e Compare January 27, 2023 20:59
jpwilliams added a commit that referenced this pull request Feb 9, 2023
…ean examples (#45)

## Breaking changes

### Function creation helpers removed

The following function creation methods have been removed and should be
replaced by using `Inngest#createFunction`:
- `createFunction`
- `createScheduledFunction`
- `createStepFunction`
- `Inngest#createScheduledFunction`
- `Inngest#createStepFunction`

```ts
import { createFunction } from "inngest";
createFunction("Example", "app/user.created", () => {});
// becomes
import { Inngest } from "inngest";
const inngest = new Inngest({ name: "App" });
inngest.createFunction("Example", "app/user.created", () => {});
```

```ts
import { createScheduledFunction } from "inngest";
createScheduledFunction("Example", "* * * * *", () => {}); // or inngest.createScheduledFunction
// becomes
import { Inngest } from "inngest";
const inngest = new Inngest({ name: "App" });
inngest.createFunction("Example", { cron: "* * * * *" }, () => {});
```

```ts
import { createStepFunction } from "inngest";
createStepFunction("Example", "* * * * *", () => {}); // or inngest.createStepFunction
// becomes
import { Inngest } from "inngest";
const inngest = new Inngest({ name: "App" });
inngest.createFunction("Example", { cron: "* * * * *" }, async ({ tools }) => {
  // Use a tool to create a step function
});
```

### Step functions are now asynchronous

In order to provide the full power of asynchronous JavaScript, step
functions are now required to be async functions, and all step tooling
will return promises instead of synchronously.

If you're using TypeScript, you'll be guided through the changes at each
stage. For example, trying to access `.id` of the new `Promise<User>`
will throw an error telling you that it must first be awaited.

```ts
import { createStepFunction } from "inngest";
import { userDb } from "./db";
import { email } from "./email";

export default createStepFunction(
  "Example",
  "app/user.created",
  ({ event, tools }) => {
    const user = tools.run("Get user email", () => userDb.get(event.userId));

    // We run synchronously, so wait for the email to be send before the alert is sent
    tools.run("Send email", () => email.sendEmail(user.email, "Welcome!"));
    tools.run("Send alert to staff", () =>
      email.sendAlert("New user created!")
    );
  }
);
```

This would be converted to the following:

```ts
import { inngest } from "./client";
import { userDb } from "./db";
import { email } from "./email";

export default inngest.createFunction( // use client instead of helper
  { name: "Example", fns: { ...userDb, ...email } }, // can pass functions to wrap in tools.run()
  "app/user.created",
  async ({ event, fns: { getUser, sendEmail, sendAlert }}) => {
    const user = await getUser(event.userId); // use fns directly that have been passed

    // We don't await these, so they are run in parallel now
    sendEmail(user.email, "Welcome!");
    sendAlert("New user created!");
  }
);
```

### Custom handlers require a `stepId`

In order to provide the parallel functionality in this PR, all handlers
created using `InngestCommHandler` must provide a `stepId` parameter
when attempting to run a function. This should be accessed via the query
string using the exported `queryKeys.StepId` enum.

```diff
run: async () => {
  if (req.method === "POST") {
    return {
      fnId: url.searchParams.get(queryKeys.FnId) as string,
+     stepId: url.searchParams.get(queryKeys.StepId) as string,
```

## Features

### Pass functions to wrap as retriable steps

When creating a function, you can now pass a `fns` key to automatically
wrap all found functions in `tools.run()` step tooling, automatically
providing your existing functionality with retries and durability.

```ts
import { inngest } from "./client";
import { userDb } from "./db";
import { email } from "./email";

export default inngest.createFunction(
  { name: "Example", fns: { ...userDb, ...email } },
  "app/user.created",
  async ({ event, fns: { getUser, sendEmail}}) => {
    const user = await getUser(event.userId);
    sendEmail(user.email, "Welcome!");
  }
);
```

## Fixes

- `user` key in event payloads can now be any value, to ensure
conflicting generated events are accepted; see #87 for further
discussion

## Related changes/issues based on this PR

- #66 
- #73 
- #74 
- #75 
- #76 
- #69 
- #43 

## SDK changes

- [x] Refactor step function tooling to be `async`
- [x] Unify `createFunction`, `createScheduledFunction`, and
`createStepFunction` under a single `createFunction` method
- [x] ~Preserve complex client-less `createFunction` helper~
  > Prefer instantiation with a client for now.
- [x] Add error-handling capabilities by giving the SDK the ability to
send back a serialised `error` as well as `data`
- [x] Allow use of regular JS tooling (`.then()`, `try/catch`, etc) in
step functions without gotchas
- [x] ~Create a new `StepOpCode` for a no-op other than `None`~
We just return an empty array.
- [x] Add ability to pass steps in as "just functions" to avoid wrapping
all user code in `tools.run()`
- [x] ~Add ability to pass steps in as "just functions" to a `new
Inngest()` client, which is merged with any steps passed directly to
`inngest.createFunction()`~
> Defer this to be implemented with #66, as this will alter generics for
`Inngest` and `InngestFunction` to aid with this change.
- [x] Hash synchronous groups of steps and throw errors if synchronous
step order doesn't match
- [x] Allow triggering steps using `stepId` query param instead of op
position codes
- [x] Add new `StepPlanned` (or similar) op code for back compat
- [ ] Create `step` alias for `tools` and deprecate `tools`
- [ ] Add a large warning when the a step function resolves, but some
tooling is still pending; we want to highlight for users that to be safe
they should make sure to await in serverless environments

## Examples

<details>
<summary>See examples</summary>

```ts
// Any type of function uses the same method.
// declare createFunction: (nameOrFunctionOpts, eventNameOrTriggerOpts, fn) => void;
inngest.createFunction("...", "demo/event.sent", () => {});
inngest.createFunction("...", { event: "demo/event.sent" }, () => {});
inngest.createFunction("...", { cron: "* * * * *" }, () => {});
```

```ts
// A step function uses the same method; just use a tool.
inngest.createFunction("...", "demo/event.sent", ({ tools: { run } }) => {
  run("Step", () => {});
});
```

```ts
// Step functions now use async functions - easier to map complex flows.
inngest.createFunction("...", "demo/event.sent", async ({ tools: { run } }) => {
  const randomNumber = await run("Get random number", () => Math.random());
  await run("Send random number", () => sendEmail("...", randomNumber));
});
```

```ts
// With async support, fire-and-forget parallel steps are easy to create - just
// trigger them all and SDK will let Inngest know of all of the pending actions.
inngest.createFunction("...", "demo/event.sent", async ({ tools: { run } }) => {
  run("Send email", () => sendEmail("..."));
  run("Send another email", () => sendEmail("..."));
  run("Send yet another email", () => sendEmail("..."));
});

// This means that the response from the SDK to Inngest is always an array of
// upcoming steps.
//
// In this case, the first call would return all three actions, as we're not
// awaiting them; the SDK gets a single synchronous tick of the event loop to
// decide what is next.
[
  { op: "Step", name: "Send email", run: true },
  { op: "Step", name: "Send another email", run: true },
  { op: "Step", name: "Send yet another email", run: true },
];
```

```ts
// Step functions can handle errors too, meaning we can use usual tools like
// try/catch.
inngest.createFunction("...", "demo/event.sent", async ({ tools: { run } }) => {
  try {
    await run("Step", () => {});
  } catch (err) {
    await run("Send error to Tim", () => sendEmail("...", err));
  }
});

// Or perhaps we want to silently handle an error case and not have it affect
// other steps.
inngest.createFunction("...", "demo/event.sent", async () => {
  await run("Send email", () => sendEmail("...")).catch(() => {
    run("Send error to Tim", () => sendEmail("...", err));
  });
});
```

```ts
// Tools such as `Promise.all` are fine too.
inngest.createFunction("...", "demo/event.sent", async ({ tools: { run } }) => {
  await Promise.all([
    run("Send email", () => sendEmail("...")),
    run("Send another email", () => sendEmail("...")),
  ]);
});
```

```ts
// We can even create parallel chains of steps that trigger immediately, follow
// their own path, then eventually come back together.
inngest.createFunction("...", "demo/event.sent", async ({ tools: { run } }) => {
  const fooStep = run("Foo", () => fooSomething())
    .then((data) => run("Foo again", () => fooSomethingElse(data)))
    .then((data) => run("Foo again again", () => fooSomethingElse(data)));

  const barStep = run("Bar", () => barSomething())
    .then((data) => run("Bar again", () => barSomethingElse(data)))
    .then((data) => run("Bar again again", () => barSomethingElse(data)));

  const [foo, bar] = await Promise.all([fooStep, barStep]);

  await run("Send email", () => sendEmail("...", { foo, bar }));
});
```

```ts
// Wrapping all user code in `run()` can be a bit verbose. One of the initial
// goals of the SDK was that steps were "just functions". If we pass those to
// our Inngest function then we can shim them with `run()` automatically, which
// makes the code look _super_ clean.
//
// The TS types and runtime JS will non-destructively filter the input and add
// shims, meaning you could pass entire structures/classes in with no bother,
// like we do here with `userDb` and `email` which may export more than just
// functions. We even retain the function's comments!
import * as userDb from "./dbs/user";
import * as email from "./email";

inngest.createFunction(
  { name: "...", fns: { ...email, ...userDb } },
  "demo/event.sent",
  async ({ event, fns: { sendEmail, getUserById } }) => {
    const user = await getUserById(event.user.id);
    await sendEmail(user.email, "...");
  }
);

// This can really help clean up functions with lots of steps, like our example
// of parallel paths above.
inngest.createFunction(
  { name: "...", fns: { ...fooLib, ...barLib, ...email } },
  "demo/event.sent",
  async ({ tools: { run } }) => {
    const fooStep = fooSomething()
      .then(fooSomethingElse)
      .then(fooSomethingElse);

    const barStep = barSomething()
      .then(barSomethingElse)
      .then(barSomethingElse);

    const [foo, bar] = await Promise.all([fooStep, barStep]);
    await sendEmail("...", { foo, bar });
  }
);
```

```ts
// Sometimes, a user may want to bundle async actions together in a single step,
// for example when something must be fetched from the DB right before sending
// an email.
//
// If this is unique to this Inngest function, we can always use `tools.run()`
// to run in-line code. If we wanted to create a reusable step, however, we just
// make a regular function.
const sendEmailToUser = async (userId: string, body: string) => {
  const user = await getUserById(userId);
  await sendEmail(user.email, body);
};

inngest.createFunction(
  { name: "...", fns: { sendEmailToUser, something } },
  "demo/event.sent",
  async ({ event }) => {
    await something();
    await sendEmailToUser(event.user.id, "...");
  }
);
```

```ts
// If we were to create a library of reusable steps, a _future_ option that is
// not in this PR could be to pass steps in to the Inngest constructor to
// provide the tooling for every function automatically.
const inngest = new Inngest<Events>({
  name: "...",
  fns: { ...email, ...userDb, ...postDb },
});

inngest.createFunction(
  "...",
  "demo/event.sent",
  async ({ event, fns: { getUserById, getPostsByTag, sendEmail } }) => {
    const user = await getUserById(event.user.id);
    const posts = await getPostsByTag(user.favouriteTag);
    await sendEmail(user.email, posts);
  }
);
```
</details>
Base automatically changed from async-await-parallel-steps to main February 9, 2023 16:17
@tonyhb
Copy link
Contributor

tonyhb commented Feb 10, 2023

I'm a huge fan of this and we should get this in with a lil rebase!

@jpwilliams
Copy link
Member Author

Closing in favour of #100.

@jpwilliams jpwilliams closed this Feb 14, 2023
jpwilliams added a commit that referenced this pull request Feb 14, 2023
…ted (#100)

## Description

Cherry pick's the core commit from #75 to clean up history and
conflicts.

---------

Co-authored-by: Jack Williams <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
Development

Successfully merging this pull request may close these issues.

2 participants