pogo

Server framework for Deno

Pogo is an easy-to-use, safe, and expressive framework for writing web servers and applications. It is inspired by hapi.

Documentation

Supports Deno v1.2.0 and higher.

Contents

• Why?
• Usage
• API
• Contributing
• License

Why?

• Designed to encourage reliable and testable applications.
• Routes are simple, pure functions that return values directly.
• Automatic JSON responses from objects.
• Built-in support for React and JSX.

Usage

Save the code below to a file named

server.js

deno run --allow-net server.js

import pogo from 'https://deno.land/x/pogo/main.ts';

const server = pogo.server({ port : 3000 });
server.router.get('/', () => {
    return 'Hello, world!';
});
server.start();

The examples that follow will build on this to add more capabilities to the server. Some advanced features may require additional permission flags or different file extensions. If you get stuck or need more concrete examples, be sure to check out the example projects.

Adding routes

A route matches an incoming request to a handler function that creates a response

Adding routes is easy, just call

server.route()

server.route()

server.route()

Add routes in any order you want to, it's safe! Pogo orders them internally by specificity, such that their order of precedence is stable and predictable and avoids ambiguity or conflicts.

server.route({ method : 'GET', path : '/hi', handler : () => 'Hello!' });
server.route({ method : 'GET', path : '/bye', handler : () => 'Goodbye!' });

server
    .route({ method : 'GET', path : '/hi', handler : () => 'Hello!' });
    .route({ method : 'GET', path : '/bye', handler : () => 'Goodbye!' });

server.route([
    { method : 'GET', path : '/hi', handler : () => 'Hello!' },
    { method : 'GET', path : '/bye', handler : () => 'Goodbye!' }
]);

You can also configure the route to handle multiple methods by using an array, or

'*'

server.route({ method : ['GET', 'POST'], path : '/hi', handler : () => 'Hello!' });

server.route({ method : '*', path : '/hi', handler : () => 'Hello!' });

Serve static files

Using

h.directory()

(recommended)

You can use

h.directory()

server.router.get('/movies/{file*}', (request, h) => {
    return h.directory('movies');
});

Using

h.file()

You can use

h.file()

Response

Content-Type

server.router.get('/', (request, h) => {
    return h.file('dogs.jpg');
});

Using byte arrays, streams, etc.

If you need more control over how the file is read, there are also more low level ways to send a file, as shown below. However, you'll need to set the content type manually. Also, be sure to not set the path based on an untrusted source, otherwise you may create a path traversal vulnerability. As always, but especially when using any of these low level approaches, we strongly recommend setting Deno's read permission to a particular file or directory, e.g.

--allow-read='.'

Using

Deno.readFile()

server.router.get('/', async (request, h) => {
    const buffer = await Deno.readFile('./dogs.jpg');
    return h.response(buffer).type('image/jpeg');
});

Using

Deno.open()

server.router.get('/', async (request, h) => {
    const stream = await Deno.open('./dogs.jpg');
    return h.response(stream).type('image/jpeg');
});

React and JSX support

JSX is a shorthand syntax for JavaScript that looks like HTML and is useful for constructing web pages

You can do webpage templating with React inside of route handlers, using either JSX or

React.createElement()

Pogo automatically renders React elements using

ReactDOMServer.renderToStaticMarkup()

Save the code below to a file named

server.jsx

deno --allow-net server.jsx

.jsx

.tsx

.jsx

// @deno-types

import React from 'https://jspm.dev/react';
import pogo from 'https://deno.land/x/pogo/main.ts';

const server = pogo.server({ port : 3000 });
server.router.get('/', () => {
    return 
Hello, world!
;
});

server.start();

Writing tests

When it comes time to write tests for your app, Pogo has you covered with

server.inject()

By injecting a request into the server directly, we can completely avoid the need to listen on an available port, make HTTP connections, and all of the problems and complexity that come along with that. You should focus on writing your application logic and

server.inject()

The server still processes the request using the same code paths that a normal HTTP request goes through, so you can rest assured that your tests are meaningful and realistic.

const response = await server.inject({
    method : 'GET',
    url    : '/users'
});

API

• pogo.server(options)

• pogo.router(options?)

• Server

  • server.inject(request)

  • server.route(route, options?, handler?)

  • server.router

  • server.start()

  • server.stop()

• Request

  • request.body

  • request.headers

  • request.host

  • request.hostname

  • request.href

  • request.method

  • request.origin

  • request.params

  • request.path

  • request.raw

  • request.referrer

  • request.response

  • request.route

  • request.search

  • request.searchParams

  • request.server

  • request.state

  • request.url

• Response

  • response.body

  • response.code(statusCode)

  • response.created(url?)

  • response.header(name, value)

  • response.headers

  • response.location(url)

  • response.permanent()

  • response.redirect(url)

  • response.rewritable(isRewritable?)

  • response.state(name, value)

  • response.status

  • response.temporary()

  • response.type(mediaType)

  • response.unstate(name)

• Response Toolkit

  • h.directory(path, options?)

  • h.file(path, options?)

  • h.redirect(url)

  • h.response(body?)

• Router

  • router.add(route, options?, handler?)

  • router.all(route, options?, handler?)

  • router.delete(route, options?, handler?)

  • router.get(route, options?, handler?)

  • router.lookup(method, path)

  • router.patch(route, options?, handler?)

  • router.post(route, options?, handler?)

  • router.put(route, options?, handler?)

  • router.routes

pogo.server(options)

Returns a

Server

const server = pogo.server();

options

Type:

object

catchAll

Type:

function

Optional route handler to be used as a fallback for requests that do not match any other route. This overrides the default 404 Not Found behavior built into the framework. Shortcut for

server.router.all('/{catchAll*}', catchAll)

const server = pogo.server({
    catchAll(request, h) {
        return h.response('the void').code(404);
    }
});

certFile

Type:

string

'/path/to/file.cert'

Optional filepath to an X.509 public key certificate for the server to read when

server.start()

keyFile

hostname

Type:

string

'localhost'

Optional domain or IP address for the server to listen on when

server.start()

'0.0.0.0'

keyFile

Type:

string

'/path/to/file.key'

Optional filepath to a private key for the server to read when

server.start()

certFile

port

Type:

number

3000

Any valid port number (

0

65535

server.start()

0

pogo.router(options?)

Returns a

Router

const router = pogo.router();

Server

The

server

pogo.server()

server.inject(request)

Performs a request directly to the server without using the network. Useful when writing tests, to avoid conflicts from multiple servers trying to listen on the same port number.

Returns a

Promise

Response

const response = await server.inject({
    method : 'GET',
    url    : '/'
});

request

Type:

object

method

Type:

string

'GET'

Any valid HTTP method, such as

GET

POST

url

Type:

string

'/'

Any valid URL path. Used to lookup the route handler.

server.route(route, options?, handler?)

Adds a route to the server so that the server knows how to respond to requests that match the given HTTP method and URL path. Shortcut for

server.router.add()

Returns the server so other methods can be chained.

server.route({ method : 'GET', path : '/', handler : () => 'Hello, World!' });

server.route({ method : 'GET', path : '/' }, () => 'Hello, World!');

server.route('/', { method : 'GET' }, () => 'Hello, World!');

route

Type:

object

string

Router

Array

method

Type:

string

Array

'GET'

Any valid HTTP method, array of methods, or

'*'

path

Type:

string

'/users/{userId}'

Any valid URL path. Used to limit which requests will trigger the route handler.

Supports path parameters with dynamic values, which can be accessed in the handler as

request.params

handler(request, h)

Type:

function

• request

  is a

  Request

  instance with properties for

  headers

  ,

  method

  ,

  url

  , and more.

• h

  is a Response Toolkit instance, which has utility methods for modifying the response.

The implementation for the route that handles requests. Called when a request is received that matches the

method

path

The handler must return one of: - A

string

object

Uint8Array

Response

response.body

Reader

File

Buffer

Error

throw

Promise

An appropriate

Content-Type

response.type()

server.router

Type:

Router

The route manager for the server, which contains the routing table for all known routes, as well as various methods for adding routes to the routing table.

server.start()

Begins listening for requests on the

hostname

port

Returns a

Promise

await server.start();
console.log('Listening for requests');

server.stop()

Stops accepting new requests. Any existing requests that are being processed will not be interrupted.

Returns a

Promise

await server.stop();
console.log('Stopped listening for requests');

Request

The

request

ServerRequest

It provides properties and methods for inspecting the content of the request.

request.body

Type:

Reader

The HTTP body value.

To get the body as a string, pass it to

Deno.readAll()

server.router.post('/users', async (request) => {
    const bodyText = new TextDecoder().decode(await Deno.readAll(request.body));
    const user = JSON.parse(bodyText);
    // ...
});

If you want more control over how the stream is processed, instead of reading it all into memory, you can read raw bytes from the body in chunks with

request.body.read()

Uint8Array

Promise

null

server.router.post('/data', (request) => {
    const buffer = new Uint8Array(20);
    const numBytesRead = await request.body.read(buffer);
    const data = new TextDecoder().decode(buffer.subarray(0, numBytesRead));
    // ...
});

request.headers

Type:

Headers

Contains the HTTP headers that were sent in the request, such as

Accept

User-Agent

request.host

Type:

string

'localhost:3000'

The value of the HTTP

Host

:

request.url.host

To get the hostname, which does not include the port number, see

request.hostname

request.hostname

Type:

string

'localhost'

The hostname part of the HTTP

Host

request.url.hostname

To get the host, which includes the port number, see

request.host

request.href

Type:

string

'http://localhost:3000/page.html?query'

The full URL associated with the request, represented as a string. Shortcut for

request.url.href

To get this value as a parsed object instead, use

request.url

request.method

Type:

string

'GET'

The HTTP method associated with the request, such as

GET

POST

request.origin

Type:

string

'http://localhost:3000'

The scheme and host parts of the request URL. Shortcut for

request.url.origin

request.params

Type:

object

Contains the name/value pairs of path parameters, where each key is a parameter name from the route path and the value is the corresponding part of the request path. Shortcut for

request.route.params

request.path

Type:

string

/page.html

The path part of the request URL, excluding the query. Shortcut for

request.url.pathname

request.raw

Type:

ServerRequest

The original request object from Deno's

http

You probably don't need this. It is provided as an escape hatch, but using it is not recommended.

request.referrer

Type:

string

The value of the HTTP

Referer

Referrer-Policy

Note that this property uses the correct spelling of "referrer", unlike the header. It will be an empty string if the header is missing.

request.response

Type:

Response

The response that will be sent for the request. To create a new response, see

h.response()

request.route

Type:

object

The route that is handling the request, as given to

server.route()

paramNames

params

segments

/

request.search

Type:

string

'?query'

The query part of the request URL, represented as a string. Shortcut for

request.url.search

To get this value as a parsed object instead, use

request.searchParams

request.searchParams

Type:

URLSearchParams

The query part of the request URL, represented as an object that has methods for working with the query parameters. Shortcut for

request.url.searchParams

To get this value as a string instead, use

request.search

request.server

Type:

Server

The server that is handling the request.

request.state

Type:

object

Contains the name/value pairs of the HTTP

Cookie

request.url

Type:

URL

The full URL associated with the request, represented as an object that contains properties for various parts of the URL,

To get this value as a string instead, use

request.href

.toString()

Response

The

response

request

request.response

h.response()

response.body

Type:

string

object

Uint8Array

Reader

The body that will be sent in the response. Can be updated by returning a value from the route handler or by creating a new response with

h.response()

response.code(statusCode)

Sets the response status code. When possible, it is better to use a more specific method instead, such as

response.created()

response.redirect()

Returns the response so other methods can be chained.

Tip: Use Deno's

status

import { Status as status } from 'https://deno.land/std/http/http_status.ts';
const handler = (request, h) => {
    return h.response().code(status.Teapot);
};

response.created(url?)

Sets the response status to

201 Created

Location

url

Returns the response so other methods can be chained.

response.header(name, value)

Sets a response header. Always replaces any existing header of the same name. Headers are case insensitive.

Returns the response so other methods can be chained.

response.headers

Type:

Headers

Contains the HTTP headers that will be sent in the response, such as

Location

Vary

response.location(url)

Sets the

Location

url

response.created()

response.redirect()

Returns the response so other methods can be chained.

response.permanent()

Only available after calling the

response.redirect()

Sets the response status to

301 Moved Permanently

308 Permanent Redirect

Returns the response so other methods can be chained.

response.redirect(url)

Sets the response status to

302 Found

Location

url

Also causes some new response methods to become available for customizing the redirect behavior:

• response.permanent()

• response.temporary()

• response.rewritable()

Returns the response so other methods can be chained.

response.rewritable(isRewritable?)

Only available after calling the

response.redirect()

Sets the response status to

301 Moved Permanently

302 Found

isRewritable

false

307 Temporary Redirect

308 Permanent Redirect

Returns the response so other methods can be chained.

response.state(name, value)

Sets the

Set-Cookie

name

value

value

Returns the response so other methods can be chained.

All of the following forms are supported:

response.state('color', 'blue');
response.state('color', { value : 'blue' });
response.state({ name : 'color', value : 'blue' });

response.status

Type:

number

418

The status code that will be sent in the response. Defaults to

200

response.temporary()

Only available after calling the

response.redirect()

Sets the response status to

302 Found

307 Temporary Redirect

Returns the response so other methods can be chained.

response.type(mediaType)

Sets the

Content-Type

mediaType

Overrides the media type that is set automatically by the framework.

Returns the response so other methods can be chained.

response.unstate(name)

Sets the

Set-Cookie

name

Returns the response so other methods can be chained.

Response Toolkit

The response toolkit is an object that is passed to route handlers, with utility methods that make it easy to modify the response. For example, you can use it to set headers or a status code.

By convention, this object is assigned to a variable named

h

h.directory(path, options?)

Creates a new response with a body containing the contents of the directory or file specified by

path

Returns a

Promise

server.router.get('/movies/{file*}', (request, h) => {
    return h.directory('movies');
});

The directory or file that is served is determined by joining the path given to

h.directory()

• A route with

  path: '/movies'

  will only serve the directory itself, meaning it will only work if the

  listing

  option is enabled (or if the path given to

  h.directory()

  is actually a file instead of a directory), otherwise a

  403 Forbidden

  error will be thrown.
• A route with

  path: '/movies/{file}'

  will only serve the directory's children, meaning that a request to

  /movies/

  will return a

  404 Not Found

  , even if the

  listing

  option is enabled.
• A route with

  path: '/movies/{file?}'

  will serve the directory itself and the directory's children, but not any of the directory's grandchildren or deeper descendants.
• A route with

  path: '/movies/{file*}'

  will serve the directory itself and any of the directory's descendants, including children and granchildren.

Note that the name of the path parameter (

file

file

options

Type:

object

listing

Type:

boolean

false

If

true

By default, directory listings are disabled for improved privacy, and instead a

403 Forbidden

Note that this option does not affect which files within the directory are accessible. For example, with a route of

/movies/{file*}

listing: false

/movies/secret.mov

/movies

listing: true

/movies/secret.mov

To control which files are accessible, you can change the route path parameter or use

h.file()

h.file(path, options?)

Creates a new response with a body containing the contents of the file specified by

path

Content-Type

Returns a

Promise

server.router.get('/', (request, h) => {
    return h.file('index.html');
});

options

Type:

object

confine

Type:

boolean

string

Deno.cwd()

Optional directory path used to limit which files are allowed to be accessed, which is important in case the file path comes from an untrusted source, such as the request URL. Any file inside of the

confine

confine

403 Forbidden

false

h.redirect(url)

Creates a new response with a redirect status. Shortcut for

h.response().redirect(url)

response.redirect()

Returns the response so other methods can be chained.

h.response(body?)

Creates a new response with an optional body. This is the same as returning the body directly from the route handler, but it is useful in order to begin a chain with other response methods.

Returns the response so other methods can be chained.

Router

Documentation: Routing

A router is used to store and lookup routes. The server has a built-in router at

server.router

pogo.router()

To copy routes from one router to another, see

router.add()

server.route()

server.router.add()

Note that you don't necessarily need to create a custom router. You only need to create your own router if you prefer the chaining syntax for defining routes and you want to export the routes from a file that doesn't have access to the server. In other words, a custom router is useful for larger applications.

const server = pogo.server();
server.router
    .get('/', () => {
        return 'Hello, World!';
    })
    .get('/status', () => {
        return 'Everything is swell!';
    });

const router = pogo.router()
    .get('/', () => {
      return 'Hello, World!';
    })
    .get('/status', () => {
      return 'Everything is swell!';
    });

const server = pogo.server();
server.route(router);

router.add(route, options?, handler?)

Adds one or more routes to the routing table, which makes them available for lookup, e.g. by a server trying to match an incoming request to a handler function.

The

route

method

path

handler

method

path

handler

Router

The

options

route

The

handler

route

options

Each argument has higher precedence than the previous argument, allowing you to pass in a route but override its handler, for example, by simply passing a handler as the final argument.

Returns the router so other methods can be chained.

const router = pogo.router().add('/', { method : '*' }, () => 'Hello, World!');

router.all(route, options?, handler?)

Shortcut for

router.add()

'*'

Returns the router so other methods can be chained.

const router = pogo.router().all('/', () => 'Hello, World!');

router.delete(route, options?, handler?)

Shortcut for

router.add()

'DELETE'

Returns the router so other methods can be chained.

const router = pogo.router().delete('/', () => 'Hello, World!');

router.get(route, options?, handler?)

Shortcut for

router.add()

'GET'

Returns the router so other methods can be chained.

const router = pogo.router().get('/', () => 'Hello, World!');

router.lookup(method, path)

Look up a route that matches the given

method

path

Returns the route object with an additional

params

router.patch(route, options?, handler?)

Shortcut for

router.add()

'PATCH'

Returns the router so other methods can be chained.

const router = pogo.router().patch('/', () => 'Hello, World!');

router.post(route, options?, handler?)

Shortcut for

router.add()

'POST'

Returns the router so other methods can be chained.

const router = pogo.router().post('/', () => 'Hello, World!');

router.put(route, options?, handler?)

Shortcut for

router.add()

'PUT'

Returns the router so other methods can be chained.

const router = pogo.router().put('/', () => 'Hello, World!');

router.routes

Type:

object

The routing table, which contains all of the routes that have been added to the router.

Contributing

See our contributing guidelines for more details.

1. Fork it.
2. Make a feature branch:

   git checkout -b my-new-feature

3. Commit your changes:

   git commit -am 'Add some feature'

4. Push to the branch:

   git push origin my-new-feature

5. Submit a pull request.

License

MPL-2.0 © Seth Holladay

Go make something, dang it.