Post a Job/Task

14min
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!
A job should not take longer than 3 minutes to run, or a timeout will occur and your job will error out. 
Example
Node.js
Curl
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)
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
Status Code
Description
Example Response
201
Success
{"ok": true}
500
Error
{"ok": false, "msg": "..."}
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. 
A hyper queue will generate an X-HYPER-SIGNATURE, if and only if you provide a secret when creating the queue.
Some frameworks, for example NextJS , will lowercase headers names ie. x-hyper-signature , so be sure to take this into account, when checking for the signature.
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:
A bad actor posts a hand-crafted job to the worker
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"
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=. 
Text
X-HYPER-SIGNATURE:
t=1643654130111,
sig=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
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:
The job's payload has not been altered
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:
Node.js
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)
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)
﻿
Need Help?
You can always reach out to our support team for any additional assistance on slack.
﻿