- v17.1.2Latest
- v17.1.1
- v17.1.0
- v17.0.0
- v16.1.0
- v16.0.0
- v15.0.0
- 14.2.0
- v14.1.1
- v14.1.0
- v14.0.0
- v13.2.5
- 13.2.4
- v13.2.3
- v13.2.2
- v13.2.1
- v13.2.0
- v13.1.0
- v13.0.1
- v13.0.0
- v12.6.2
- v12.6.1
- v12.6.0
- v12.5.0
- v12.4.0
- v12.3.1
- v12.3.0
- v12.2.0
- v12.1.0
- v12.0.1
- v12.0.0
- v11.1.0
- v11.0.0
- v10.6.0
- v10.5.1
- v10.4.0
- v10.3.0
- v10.2.1
- v10.2.0
- v10.1.1
- v10.1.0
- v10.0.0
- v9.0.1
- v9.0.0
- v8.0.0
- v7.7.0
- v7.6.3
- v7.6.2
- v7.6.1
- v7.6.0
- v7.5.0
- v7.4.1
- v7.4.0
- v7.3.0
- v7.2.0
- v7.1.0
- v7.0.0
- v6.5.1
- v6.5.0
- v6.4.2
- v6.4.1
- v6.4.0
- v6.3.2
- v6.3.1
- v6.3.0
- v6.2.0
- v6.1.0
- v6.0.2
- v6.0.1
- v6.0.0
- v5.4.0
- v5.3.1
- v5.3.0
- v5.2.0
- v5.1.1
- v5.1.0
- v5.0.0
- v4.0.0
- v3.7.0
- v3.6.0
- v3.5.0
- v3.4.0
- v3.3.0
- v3.2.0
- v3.1.0
- v3.0.0
- v2.10.0
- v2.9.0
- v2.8.0
- v2.7.0
- v2.6.0
- v2.5.0
- v2.4.0
- v2.3.0
- v2.2.0
- v2.1.0
- v2.0.0
- v1.0.0
oak
A middleware framework for Deno’s http server, including a router middleware.
This middleware framework is inspired by Koa and middleware router inspired by koa-router.
Application, middleware, and context
The Application
class wraps the serve()
function from the http
package. It
has two methods: .use()
and .listen()
. Middleware is added via the
.use()
method and the .listen()
method will start the server and start
processing requests with the registered middleware.
A basic usage, responding to every request with Hello World!:
import { Application } from "https://deno.land/x/oak/mod.ts";
(async () => {
const app = new Application();
app.use(ctx => {
ctx.response.body = "Hello World!";
});
await app.listen("127.0.0.1:8000");
})();
The middleware is processed as a stack, where each middleware function can control the flow of the response. When the middleware is called, it is passed a context and reference to the “next” method in the stack.
A more complex example:
import { Application } from "https://deno.land/x/oak/mod.ts";
(async () => {
const app = new Application();
// Logger
app.use(async (ctx, next) => {
await next();
const rt = ctx.response.headers.get("X-Response-Time");
console.log(`${ctx.request.method} ${ctx.request.url} - ${rt}`);
});
// Timing
app.use(async (ctx, next) => {
const start = Date.now();
await next();
const ms = Date.now() - start;
ctx.response.headers.set("X-Response-Time", `${ms}ms`);
});
// Hello World!
app.use(ctx => {
ctx.response.body = "Hello World!";
});
await app.listen("127.0.0.1:8000");
})();
Context
The context passed to middleware has several properties:
.app
A reference to the
Application
that is invoking this middleware..request
The
Request
object which contains details about the request..response
The
Response
object which will be used to form the response sent back to the requestor..state
A “map” of application state, which can be strongly typed by specifying a generic argument when constructing and
Application
.
The context passed to middleware has one method:
.throws()
Throws an
HTTPError
, which subclass is identified by the first argument, with the message being passed as the second.
Unlike other middleware frameworks, context
does not have a significant
amount of aliases. The information about the request is only located in
.request
and the information about the response is only located in
.response
.
Request
The context.request
contains information about the request. It contains
several properties:
.hasBody
Set to
true
if the request has a body, orfalse
if it does not. It does not validate if the body is supported by the built in body parser though..headers
The headers for the request, an instance of
Headers
..method
A string that represents the HTTP method for the request.
.path
The path part of the request URL.
.search
The raw search string part of the request.
.searchParams
An instance of
URLSearchParams
which contain the parsed value of the search part of the request URL..severRequest
The original
net
server request..url
TODO currently the same as
.path
, logic needs to be added to determine the requested host.
And several methods:
.accepts(...types: string[])
Negotiates the content type supported by the request for the response. If no content types are passed, the method returns a prioritized array of accepted content types. If content types are passed, the best negotiated content type is returned. If there is no content type matched, then
undefined
is returned..acceptsCharsets(...charsets: string[])
To be implemented.
.acceptsEncodings(...encodings: string[])
Negotiates the content encoding supported by the request for the response. If no encodings are passed, the method returns a prioritized array of accepted encodings. If encodings are passed, the best negotiated encoding is returned. If there are no encodings matched, then
undefined
is returned..acceptsLanguages(...languages: string[])
To be implemented.
.body()
The method resolves to a parsed version of the request body. Currently oak supports request body types of JSON, text and URL encoded form data. If the content type of the request is not supported, the request will be rejected with a 415 HTTP Error.
If the content type is supported, the method resolves with an object which contains a
type
property set to"json"
,"text"
,"form"
, or"undefined"
and avalue
property set with the parsed value of the property. For JSON it will be the parsed value of the JSON string. For text, it will simply be a string and for a form, it will be an instance ofURLSearchParams
. For an undefined body, the value will beundefined
.For more advanced use cases of the body, the original server request is available and contains a
.body()
and.bodyStream()
methods.
Automatic response body handling
When the response Content-Type
is not set in the headers of the .response
,
oak will automatically try to determine the appropriate Content-Type
. First
it will look at .response.type
. If assigned, it will try to resolve the
appropriate media type based on treating the value of .type
as either the
media type, or resolving the media type based on an extension. For example if
.type
was set to ".html"
, then the Content-Type
will be set to
"text/html"
.
If .type
is not set with a value, then oak will inspect the value of
.response.body
. If the value is a string
, then oak will check to see if
the string looks like HTML, if so, Content-Type
will be set to text/html
otherwise it will be set to text/plain
. If the value is an object, other
than a Uint8Array
or null
, the object will be passed to JSON.stringify()
and the Content-Type
will be set to application/json
.
Router
The Router
class produces middleware which can be used with an Application
to enable routing based on the pathname of the request.
Basic usage
The following example serves up a RESTful service of a map of books, where
http://localhost:8000/book/
will return an array of books and
http://localhost:8000/book/1
would return the book with ID "1"
:
import { Application, Router } from "https://deno.land/x/oak/mod.ts";
const books = new Map<string, any>();
books.set("1", {
id: "1",
title: "The Hound of the Baskervilles",
author: "Conan Doyle, Author"
});
(async () => {
const router = new Router();
router
.get("/", context => {
context.response.body = "Hello world!";
})
.get("/book", context => {
context.response.body = Array.from(books.values());
})
.get("/book/:id", context => {
if (context.params && books.has(context.params.id)) {
context.response.body = books.get(context.params.id);
}
});
const app = new Application();
app.use(router.routes());
app.use(router.allowedMethods());
await app.listen("127.0.0.1:8000");
})();
Static content
The function send()
is designed to serve static content as part of a
middleware function. In the most straight forward usage, a root is provided
and requests provided to the function are fulfilled with files from the local
file system relative to the root from the requested path.
A basic usage would look something like this:
import { Application, send } from "https://deno.land/x/oak/mod.ts";
(async () => {
const app = new Application();
app.use(async context => {
await send(context, context.request.path, {
root: `${Deno.cwd()}/examples/static`,
index: "index.html"
});
});
await app.listen("127.0.0.1:8000");
})();
There are several modules that are directly adapted from other modules. They have preserved their individual licenses and copyrights. All of the modules, including those directly adapted are licensed under the MIT License.
All additional work is copyright 2018 - 2019 the oak authors. All rights reserved.