Post a Job/Task

POST /{appname}/queue/{servicename}

A Job or Task is a JSON document that you would like to pass to the queue's target endpoint for processing. This asynchronous flow will work great for serverless APIs that can do background processing without holding up the request/response process.

Parameters

Path Parameters

• appname - string - the name of your hyper cloud application.
• servicename - string - The name of your hyper cloud service

Request Body

This request body needs to be a JSON object that can be made of any fields you would like to use. It should contain the context needed for your worker endpoint to successfully process the job!

Example

import { connect } from 'hyper-connect'

const hyper = connect(process.env.HYPER)

const result = await hyper.queue.enqueue({ type: "NEW_MOVIE", id: "movie-1" })

console.log(result)

Responses

Verifying jobs from hyper queue

When a hyper queue receives a job, it will POST the job payload to your provided target URL for processing.

A hyper queue can also optionally sign the job it sends to your queue's target URL by including a signature in each job's X-HYPER-SIGNATURE header. This allows the worker to verify that the job was sent by its corresponding hyper queue, not by a third party, and is unaltered.

Why would you want to verify a job?

Since your worker is a public URL, anyone may attempt to POST jobs to it, for processing. This is a potential vector for malicious actors to spoof your worker, causing it to process jobs that did not originate from your hyper queue, or have been altered in some way:

1. A bad actor posts a hand-crafted job to the worker
2. A bad actor intercepts a legitimate job, sent by your hyper queue, and alters the payload, before forwarding it to your worker. This is known as a "man in the middle attack"
3. A bad actor intercepts a legitimate job, sent by your hyper queue, and then sends it again, deliberately delays its transmission, or modifies the timestamp. This is known as a "replay attack"

By including a signature in each job's X-HYPER-SIGNATURE header, your worker can verify that the job was sent by your hyper queue, not by a third party, and is unaltered

How to verify the signature

The X-HYPER-SIGNATURE header included in each signed job contains a timestamp and a signature. The timestamp is prefixed by t=, and the signature is prefixed by sig=.

X-HYPER-SIGNATURE:
t=1643654130111,
sig=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

A hyper queue generates signatures using a hash-based message authentication code (HMAC) with SHA-256. To verify the signature included on the job, follow the steps below.

Step 1: Extract the timestamp and signatures from the header 

Split the header, using the , character as the separator, to get a list of elements. Then split each element, using the = character as the separator, to get a prefix and value pair.

The value for the prefix t corresponds to the timestamp, and sig corresponds to the signature. You can discard all other elements.

Step 2: Prepare the signed payload string 

The "signed payload" string is created by concatenating:

• The timestamp (as a string)
• The character: .
• The stringified JSON payload (that is, the request body) ie. JSON.stringify(body, null, 0)

Step 3: Determine the expected signature 

Compute an HMAC with the SHA256 hash function. Use your hyper queue secret as the key, and use the signed payload string as the message.

Step 4: Compare the signatures 

Compare the signature, in the sig value of the X-HYPER-SIGNATURE header, to your generated expected signature. If the signatures match, you can be sure that:

1. The job's payload has not been altered
2. The job's timestamp has not been altered

For additional security, you may also compare the time signature value t of the X-HYPER-SIGNATURE header, to the current time, then decide if the difference is within your worker's tolerance. For example, your worker may have a constraint where it should only process jobs if the job was sent within the last 5 minutes. Remember, by verifying the sig value, you also verify that the time signature was not altered, and is, therefore, safe to compare.

Example

Here's an example of how your worker might verify an incoming job using express:

import forge from 'node-forge'
import express from 'express'

const fiveMins = 5 * 60 * 1000
const secret = process.env["WORKER_SECRET"]

// express middleware
function verifySignature (req, res, next) {
  const [timepart, sigpart] = req.headers['x-hyper-signature'].split(',')

  const [, time] = timepart.split('t=')
  const [, sig] = sigpart.split('sig=')

  const hmac = forge.hmac.create();
  hmac.start('sha256', secret);
  hmac.update(`${time}.${JSON.stringify(req.body, null, 0)}`);
  const computed = hmac.digest().toHex()
  
  // payload or time signature was tampered with
  if (computed !== sig) {
    return res.setStatus(401).send('Unauthorized')
  }

  const now = new Date().getTime()
  const dateSent = new Date(time).getTime()
  const diff = now - dateSent

  // timestamp in the future, or not within 5 minutes   
  if (diff < 0 || diff > fiveMins) {
    return res.setStatus(422).send('Timestamp not within acceptable range')
  }

  // continue
  next()
}

function handleQueueJob (req, res) {
  const { body } = req
  // processing
  res.json({ ok: true })
}

const app = express()

app.post('/', express.json(), verifySignature, handleQueueJob)

app.listen(3000)