Codehooks

Codehooks are JavaScript functions which can intercept REST API calls to your database. Codehooks gives you greater flexibility and power than using webhooks.

Some typical use-cases for codehooks are:

• custom logic
• validation and calculation
• system integration

🚀 If you like the codehooks concept of restdb.io, please also check out our new backend service: codehooks.io. It integrates Javascript serverless functions with a document database, a key/value database, a message queue and a CRON-like job system. A powerful CLI lets you instantly deploy new code.

Codehooks can also run as background jobs to perform tasks at specific times or intervals (using crontab).

A codehook is a plain JavaScript function with a specific name to indicate when it's invoked, e.g.

function beforeGET(req, res) {
    ...
    res.end();
}

This function is called before a GET request.

Codehooks are created in the Collection settings, under the "Codehook" tab.

Codehook API

The codehooks listed here intercept API traffic and internal traffic to your database. They are invoked either before or after combined with one of the http verbs: GET, POST, PUT and DELETE. Only the combinations listed here are available.

Async/await and promise support

Codehooks now also support using async/await and/or promises. You can now avoid using callback functions and nesting when calling database API or network API functions. Ex:

const beforePOST = async (req,res) => {
    const cars = await db.get("/rest/automobiles");
    const car_exists = cars.find(car => car.name === req.body.carname);
    res.end({"data": {car_exists}});
}

Database API functions

Network API functions

Utility API functions

Return values from a codehook

A codehook must call res.end() when it is done. Failing to to so will lead to a timeout, and finally degrading the performance of your system.

Examples

beforeGET

var beforeGET = function(req, res) {
    log.debug("Calling get ", req.query, req.hint);
    // modify all queries to only show people with Hunter as lastname
    req.query.lastname = "Hunter";
    res.send({"query": req.query});
}

beforeGET with error

function beforeGET(req, res) {
    if (req.hint["#usersession"].email) {
        // logged in session allowed
        res.end();
    } else {
        // check something, e.g. JWT token
        res.end({"error": {"statuscode": 401, "message": "Forbidden to GET"}});
    }
}

beforePUT / PATCH

// helper function
function validate(field) {
    // field must contain the string London or Berlin
    if (!/london|berlin/.test(field)) {
        var validation = [
            {field: "address",message:"not valid, must be London or Berlin"}
        ];
        return validation;
    } else {
        return null;
    }
}
// codehook
function beforePUT(req, res){
    log.debug("PUT: ",req.body);
    // call a helper function for custom validation
    var errors = validate(req.body.address);
    if (errors){
        res.end({"error": errors});
    } else {
        // add a calculated field
        const tax = (req.body.salary * 0.33).toFixed(2); 
        res.end({"data": {tax}});
    }
}

afterPUT / PATCH

function afterPUT(req, res){
    log.debug("Inside after PUT, data is saved as", req.body);
        ...
    res.end();   
}

beforePOST

function beforePOST(req, res){
    log.debug("POST: ",req.body);
    ...
    res.end();
}

afterPOST

function afterPOST(req, res){
    log.debug("POST after: ",req.body);
    ...
    res.end();
}

beforeDELETE

function beforeDELETE(req, res){
    log.debug("Inside DELETE ",req.body);
    res.end();
}

Shared settings

You can access shared settings of your database using "context.settings":

function beforePOST(req, res){
    var zap_url = context.settings.zap_url;
        ...
    res.end();
}

Logging

As you seen in the examples above, you can log stuff from inside a codehook. The output can be seen in the Rest inspector. Use different log levels to better filter your log.

...
log.info("All is well");
log.debug("what's going on with", a, b, c);
log.error("Sorry, that broke: ", brokendata);
log.fatal("Yaiks, this should not happen");
...

Network calls from your codehook

A codehook function can perform network calls to other system using an the request API.

function afterPOST(req, res) {
    var opt = {
        method: 'GET',
        headers : {
            'User-Agent' : 'restdb.io (codehook)'
        },
        url: "http://fancyservice.io/api/foo"
    };
    request(opt, function(error, response, data){
        if(response.statusCode !== 200){
            log.error('Invalid Status Code Returned:', response.statusCode);
            res.end({error:[{message:"Unable to call fancyservice"}]});
            return
        }
        var json = JSON.parse(data);
        log.info("Got data: ",response.statusCode, json.length);
        // do something with json data
        ...
        res.end();
    });
}

// POST|PUT|DELETE
request({
    url: url,
    method: "POST | PUT | DELETE",
    json: true,
    headers: {
        "content-type": "application/json",
    },
    body: jsondata
    }, function(error, response, body) {
        ...
    });

Database calls from your codehook

db.get("/rest/customer", {"name": "Jane"}, {$max: 5}, function (err, results) {
    log.debug("Done get: ",err, results);
    ...
    res.end();
});

Send email

var htmlmail = "<h1>Hello</h1><p>Dear customer ...</p>";
var mailopt = {
      to: "bg@ms.com",
      subject: "Issue report: "+body.ticket,
      html: htmlmail,
      company: "My company Inc"
    };
    sendMail(mailopt, function(maildata){
        res.end();
    });

Post a message to Slack

var slackhookurl = context.settings.slack.url;
var slackopt = {
        "message": ":loudspeaker:\n New mezz:  \n Hello Slack!",
        "slackhookurl": slackhookurl,
        "channel": "#dev"
}
// post to Slack
slack(slackopt, function(){
  res.end(); 
}); 

JWT decoding

var token = req.hint['#headers'].authorization.split(' ')[1];
auth.decode_jwt(token, function(jwterr, jwttoken){
        log.debug("JWT", jwterr, jwttoken);
                …
        res.end();    
 })

JWT verification

var token = req.hint['#headers'].authorization.split(' ')[1];
var secret = "my xxx secret key";
auth.verify_jwt(token, secret, function(jwterr, jwttoken){
        log.debug("JWT", jwterr, jwttoken);
                …
        res.end();
 })

Background hooks

Records in the System_jobs collection are used to schedule tasks that invokes your codehooks.

Creating jobs in the System_jobs collection.

You can check the status of any current job in the System_log collection. It shows the res.end(...) output from a job. Any log.debug() statements can be inspected with the Rest inspector.

Crontab expressions

A crontab expression is a special string with five components that builds an expression for a job schedule: E.g. run job each 10. th minute: */10 * * * *. Tip: let https://crontab.guru help you build your expression.

Example code:

function runJob(req, res) {
    log.debug("Inside a background job");
    ...
    res.end();
}

Warning

It's important to understand that a codehook function runs in a confined space with limited rights. It will not execute in the case of:

• syntax errors
• not explicitly returning with res.end()
• not returning within x seconds
• hacking attempts and other malicious code (may lead to blacklisting of account)