A typed SDK for zeplo.io
Depending on whether you're using API Routes or Router Handlers, paste the following:
Pages Router:
pages/api/queues/email.ts
:
import { Queue } from "zeplo-sdk/dist/next-pages";
export default Queue(
"api/queues/email", // 👈 the route it's reachable on
async job => {
await email.send( ... )
},
{
baseUrl: "your-website.com",
token: "your-zeplo-token"
}
);
App Router:
app/api/queues/email/route.ts
:
import { Queue } from "zeplo-sdk/dist/next-app";
export const EmailQueue = Queue(
"api/queues/email", // 👈 the route it's reachable on
async job => {
await email.send( ... )
},
{
baseUrl: "your-website.com",
token: "your-zeplo-token"
}
);
export const POST = EmailQueue;
Up top, we're importing Queue
, which is a function that we use to declare a new Queue and export it as default.
Queue
takes three arguments.
- The first one is the location of the API Route it's been declared in. This is required for the Zeplo server to know where jobs need to be sent upon execution.
- The second one is a worker function that actually executes the job. In this example, it sends an email.
- The third one is a set of options, including all common options from the zeplo documentation.
Now that we declared the Queue, using it is straight forward. Simply import it and enqueue a new job:
// Pages Router
import EmailQueue from "pages/api/queues/email";
// App Router
import { EmailQueue } from "app/api/queues/email"
// could be some API route / getServerSideProps / ...
export default async (req, res) => {
await EmailQueue.enqueue(
..., // job to be enqueued
{ delay: 10000 } // scheduling options
)
};
Calling .enqueue
will trigger a call to the Quirrel server to enqueue a new job. After 10 seconds, when the job is due, the Queue's worker function will receive the job payload and execute it.
All common options from the zeplo documentation are available. JSDoc and Typescript typings should help you find them.
There are three ways that Zeplo can be used:
production
: Callingzeplo.to
as expected. Default value.direct
: The easiest way to run Zeplo in your development environment is to simply remove the zeplo.to/ prefix based on an environment variable. This approach has the advantage that in development, errors are thrown directly which can lead to easier debugging 🙌. The downside is that it becomes a blocking promise and won't resolve until the endpoint is finished.dev-server
: Callslocalhost:4747
for use withzeplo dev
, a local dev server that can be used during development. It implements the same API as zeplo.to.
A 32-character-long secret used for end-to-end encryption of your jobs. Can be generated using openssl rand -hex 16
or random.org. The token
does tell zeplo that you enqueued the job but the token isn't carried into your endpoint, so you need a method for allowing open access for running jobs.
If your secret is leaked, move into the oldSecrets
array and replace your encryptionSecret
. Once all jobs that were encrypted with the old secret executed, remove oldSecrets
.
By default, your jobs are serialized and deserialized using JSON.[parse,stringify]
. You can replace this with your own serializer. Superjson is my favorite.
By default, your deserialized jobs are just cast to your Queue<Payload>
typescript type. You can provide a schema for runtime validating the type. Zod is my favorite.
Variable | Meaning |
---|---|
ZEPLO_TOKEN |
Access token for Zeplo. |
ZEPLO_BASE_URL |
The base URL of your application's deployment. |
ZEPLO_API_URL |
The endpoint your Quirrel Server is running under, e.g. zeplo.to . |
ZEPLO_ENCRYPTION_SECRET |
A 32-character-long secret used for end-to-end encryption of your jobs. |
ZEPLO_OLD_SECRETS |
Leaked encryptionSecret s to continue decrypting them in the meantime. |