Routing & Configuring Policies

If you're using Intrinsic for Lambda then none of the information on this page is applicable.

Here's our example Intrinsic entry point file from before:

const intrinsic = require('@intrinsic/intrinsic');

intrinsic(__filename)
  .loadPolicies('./intrinsic-policy.js')
  .run('./server.js');

In this example we reference a file called intrinsic-policy.js. It is this file which contains our actual policies.

Here is an example of a intrinsic-policy.js file with no polices set:

'use strict';
const { HttpServer } = require('@intrinsic/intrinsic');
const server = new HttpServer({ port: process.env.PORT });

server.allSandboxes((policy) => {
  // `policy` will apply to every incoming route on this server
});

server.fallback((policy) => {
  // `policy` will apply to any unconfigured incoming route on this server
});

server.addSandbox('get', '/example', (policy) => {
  // `policy` will apply to exactly incoming `GET /example` requests to this
  // server
});

module.exports = server;

Throughout this document we will name these files intrinsic.js and intrinsic-policy.js, but there is no real requirement to do so. These fields are in charge of initializing Intrinsic and eventually requiring the "real" application file, in this case named server.js.

Within the .allSandboxes(), .fallback(), .addSandbox(), all of the policy. method calls need to be performed synchronously. For example, you cannot wait for policy-related information to download and then apply the policies once the download is complete. If you do need to perform asynchronous work then do so ahead of time.

Another important note is that you must let your application code be loaded by Intrinsic (by setting the correct application filename and calling run()), instead of you manually calling require() from the policy file. Intrinsic needs to load your handler itself to ensure that all application code (and any other code your application code ends up require-ing) is subject to policy enforcement.

Policies defined in your intrinsic-policy.js file are applied when an incoming request matches the route used by a particular policy.

server.addSandbox(method, path, policy)

These policies are called when an incoming HTTP request matches the route pattern and the HTTP method. The path parameter accepts the glob syntax.

Note: Only the first policy which matches an incoming request will be applied. For example, if you first define a policy for GET /users/*, and later define a policy for GET /users/intrinsic, the first policy will be applied when a request for GET /users/intrinsic is made.

Here is what a specific route policy might look like:

server.addSandbox('get', '/example', (policy) => {
  // `policy` will apply to exactly incoming `GET /example` requests to this
  // server
});

The method in routes.addSandbox is the name of the HTTP method. The usual list of HTTP methods, such as get, post, put, patch, delete, head, options, trace, and connect all work; if it suits your stylistic needs, addSandbox also accepts the method name in all caps.

server.allSandboxes(policy)

This policy is called for every single route regardless of whether or not it has been defined.

server.allSandboxes((policy) => {
  // `policy` will apply to every incoming route on this server
});

This policy is mostly useful in situations where your application is configuring singletons, or if it otherwise performs some I/O operations at startup time.

server.fallback(policy)

The fallback route is called when an incoming request does not match any of the specific routes you've defined.

server.fallback((policy) => {
  // `policy` will apply to any unconfigured incoming route on this server
});