Server

The Server function imported from azle allows you to build canisters (ICP applications) that act as HTTP servers on ICP. These servers can serve static files or act as API backends, or both.

Here's an example of a very simple HTTP server:

import { Server } from 'azle';
import { createServer } from 'http';

export default Server(() => {
    return createServer((req, res) => {
        res.write('Hello World!');
        res.end();
    });
});

Once deployed you can access your server at a URL like this: http://bkyz2-fmaaa-aaaaa-qaaaq-cai.localhost:8000. You can use any HTTP client to interact with your server, such as curl, fetch, or a web browser. See the Interacting with your canister section of the deployment chapter for help in constructing your canister URL.

The default export of your main module must be the result of calling Server, and the callback argument to Server must return a Node.js http.Server. The main module is specified by the main property of your project's dfx.json file. The dfx.json file must be at the root directory of your project.

The callback argument to Server can be asynchronous:

import { Server } from 'azle';
import { createServer } from 'http';

export default Server(async () => {
    const message = await asynchronousHelloWorld();

    return createServer((req, res) => {
        res.write(message);
        res.end();
    });
});

async function asynchronousHelloWorld() {
    // do some asynchronous task
    return 'Hello World Asynchronous!';
}

Express

Express is one of the most popular backend JavaScript web frameworks, and it's the recommended way to get started building servers in Azle. Here's the main code from the hello_world example:

import { Server } from 'azle';
import express, { Request } from 'express';

let db = {
    hello: ''
};

export default Server(() => {
    const app = express();

    app.use(express.json());

    app.get('/db', (req, res) => {
        res.json(db);
    });

    app.post('/db/update', (req: Request<any, any, typeof db>, res) => {
        db = req.body;

        res.json(db);
    });

    app.use(express.static('/dist'));

    return app.listen();
});

jsonStringify

When working with res.json you may run into errors because of attempting to send back JavaScript objects that are not strictly JSON. This can happen when trying to send back an object with a BigInt for example.

Azle has created a special function called jsonStringify that will serialize many ICP-specific data structures to JSON for you:

import { jsonStringify, Server } from 'azle';
import express, { Request } from 'express';

let db = {
    bigInt: 0n
};

export default Server(() => {
    const app = express();

    app.use(express.json());

    app.get('/db', (req, res) => {
        res.send(jsonStringify(db));
    });

    app.post('/db/update', (req: Request<any, any, typeof db>, res) => {
        db = req.body;

        res.send(jsonStringify(db));
    });

    app.use(express.static('/dist'));

    return app.listen();
});

Limitations

For a deep understanding of possible limitations you may want to refer to The HTTP Gateway Protocol Specification.

  • The top-level route /api is currently reserved by the replica locally
  • The Transfer-Encoding header is not supported
  • gzip responses most likely do not work
  • HTTP requests and responses are generally limited to ~2 MiB
  • You cannot set HTTP status codes in the 1xx range