INN-2754 Add support for INNGEST_DEV

[jpwilliams]

Summary

Adds support for INNGEST_DEV and a new isDev option on the client.

This lightly refactors the current checks based around isProd and skipDevServer(), which were getting a little difficult to read.

• The SDK now has two "modes:" "dev" and "cloud".
• Each mode is either explicit or inferred. An inferred mode means that the current (v3.x.x) version of the SDK can make a decision to attempt to contact the Dev Server. Future versions will remove this and default to "cloud" mode.
• Setting the INNGEST_DEV environment variable or the isDev client option explicitly sets the mode to either "cloud" or "dev".
• INNGEST_DEV accepts some sensible defaults. We'll recommend 1 to explicitly set "dev" mode and 0 to explicitly set "cloud" mode, though it also accepts "true", "y", "no", etc.
• Explicitly setting either mode also sets the event ingestion and syncing URLs. They continue to be further overwritten by passing INNGEST_BASE_URL, INNGEST_API_BASE_URL, and INNGEST_EVENT_API_BASE_URL.

Note

To support many runtimes and environments, environment variables are not always accessible a) at all times, and b) on process.env. Sometimes environment variables are accessed via different global objects, or sometimes runtime objects that are passed to requests.

For this reason, handling environment variables is more complex and relies on making best guesses during instantiation, then later making another decision when we have access to the environment.

Supersedes both #424 and #425.

Checklist

• Added a docs PR documenting these modes and the new environment variables that references this PR
• Added unit/integration tests
• Added changesets if applicable
• Push env-related changes to the OS SDK Spec

Related

• INN-2754
• Supersedes Remove prod check to enable integration tests with dev server #424
• Supersedes Allow extending a serve handler by overriding the existing isProduction #425
• Add docs for INNGEST_DEV and isDev website#679

[changeset-bot]

🦋 Changeset detected

Latest commit: bc74a5a

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
inngest	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[inngest-release-bot]

A user has added the prerelease/inngest label, so this PR will be published to npm with the tag pr-488. It will be updated with the latest changes as you push commits to this PR.

You can install this prerelease version with:

npm install inngest@pr-488

The last release was built and published from bc74a5a.

[goodoldneon]

LGTM, but the combination of the 2 modes + explicit/implicit is a bit of a mind f 😄

[tonyhb]

One additional thought: the INNGEST_DEV variable in the Go SDK also controls the INNGEST_BASE_URL; if you set INNGEST_DEV=http://192.168.1.200 then dev mode is enabled and we use the given URL as the dev server. I think this makes lots of sense for development and would also like to standardize around this in the future. Not necessarily for this PR.

[jpwilliams]

@tonyhb: One additional thought: the INNGEST_DEV variable in the Go SDK also controls the INNGEST_BASE_URL; if you set INNGEST_DEV=http://192.168.1.200 then dev mode is enabled and we use the given URL as the dev server. I think this makes lots of sense for development and would also like to standardize around this in the future. Not necessarily for this PR.

Yeah, I was thinking of this too. There are so many ways to configure it at this point, though; I'm worried about perpetually making this more and more complex.

• Check serve() arguments
  • If serve({ baseUrl }) then baseUrl
• Check explicit environment variables
  • If INNGEST_API_BASE_URL then use that
  • If INNGEST_BASE_URL then use that
• Check new Inngest() arguments
  • If new Inngest({ baseUrl }) then baseUrl
  • If new Inngest({ isDev: true }) then http://localhost:8288
• Check explicit dev environment variables
  • If INNGEST_DEV=0 then https://api.inngest.com
  • If INNGEST_DEV=1 then http://localhost:8288
  • If INNGEST_DEV=[A_URL] then [A_URL]
• Use isProduction() check in serve handler, e.g. "inngest/next"
  • If returns true then https://api.inngest.com
  • If returns false, try http://localhost:8288 but fall back to https://api.inngest.com
  • If returns or is undefined, perform inferred prod checks, e.g. NODE_ENV, CF_PAGES
    • If dev mode is inferred from this, try http://localhost:8288 but fall back to https://api.inngest.com
• If nothing else matched, default to https://api.inngest.com

TypeScript also has to perform most of these checks twice, as environment variables can sometimes be delayed and given in request args instead of in the actual environment.

tbh the end result is that (mostly) the user only has to care about a single environment variable. I doubt that the ordering of these will be much of a consideration/issue for most.

[sylwiavargas]

Thank you! Looks good. I left a few suggestions on language but I'm approving already.