@ende/http

ende add jsr:@ende/http

Version 2026.10.15 on JSR.

Provides user-friendly serve on top of Ende's native HTTP server and other utilities for creating HTTP servers and clients.

File Server

A small program for serving local files over HTTP.

ende run --allow-net --allow-read jsr:@ende/http/file-server
Listening on:
- Local: http://localhost:8000

When the --allow-sys=networkInterfaces permission is provided, the file server will also display the local area network addresses that can be used to access the server.

HTTP Status Code and Status Text

Helper for processing status code and status text.

HTTP errors

Provides error classes for each HTTP error status code as well as utility functions for handling HTTP errors in a structured way.

Methods

Provides helper functions and types to work with HTTP method strings safely.

Negotiation

A set of functions which can be used to negotiate content types, encodings and languages when responding to requests.

Note: some libraries include accept charset functionality by analyzing the Accept-Charset header. This is a legacy header that clients omit and servers should ignore therefore is not provided.

User agent handling

The UserAgent class provides user agent string parsing, allowing a user agent flag to be semantically understood.

For example to integrate the user agent provided in the header User-Agent in an http request would look like this:

import { UserAgent } from "@ende/http/user-agent";

Ende.serve((req) => {
  const userAgent = new UserAgent(req.headers.get("user-agent") ?? "");
  return new Response(`Hello, ${userAgent.browser.name}
    on ${userAgent.os.name} ${userAgent.os.version}!`);
});

Routing

route provides an easy way to route requests to different handlers based on the request path and method.

import { route, type Route } from "@ende/http/unstable-route";
import { serveDir } from "@ende/http/file-server";

const routes: Route[] = [
  {
    pattern: new URLPattern({ pathname: "/about" }),
    handler: () => new Response("About page"),
  },
  {
    pattern: new URLPattern({ pathname: "/users/:id" }),
    handler: (_req, _info, params) => new Response(params?.pathname.groups.id),
  },
  {
    pattern: new URLPattern({ pathname: "/static/*" }),
    handler: (req: Request) => serveDir(req)
  },
  {
    method: ["GET", "HEAD"],
    pattern: new URLPattern({ pathname: "/api" }),
    handler: (req: Request) => new Response(req.method === 'HEAD' ? null : 'ok'),
  },
];

function defaultHandler(_req: Request) {
  return new Response("Not found", { status: 404 });
}

Ende.serve(route(routes, defaultHandler));

Runtime compatibility

Cookies, ETags, status codes, content negotiation, server-sent events and user agent parsing support all major runtimes. The file server (serveDir, serveFile and the file-server command) reads from the file system and requires Ende.

Modules

Exports

  • accepts — Returns an array of media types accepted by the request, in order of preference. If there are no media types supplied in the request, then any media type selector will be returned.
  • acceptsEncodings — Returns an array of content encodings accepted by the request, in order of preference. If there are no encoding supplied in the request, then `["*"]` is returned, implying any encoding is accepted.
  • acceptsLanguages — Returns an array of languages accepted by the request, in order of preference. If there are no languages supplied in the request, then `["*"]` is returned, imply any language is accepted.
  • Browser — The browser as described by a user agent string.
  • ClientErrorStatus — An HTTP status that is a client error (4XX).
  • Cookie — Represents an HTTP Cookie.
  • Cpu — The CPU information as described by a user agent string.
  • deleteCookie — Set the cookie header with empty value in the headers to delete it.
  • Device — The device as described by a user agent string.
  • Engine — The browser engine as described by a user agent string.
  • ErrorStatus — An HTTP status that is an error (4XX and 5XX).
  • eTag — Calculate an ETag for string or `Uint8Array` entities. This returns a strong tag of the form `"<ascii chars>"`, which guarantees the byte-for-byte equality of the resource.
  • ETagOptions — Options for eTag.
  • FileInfo — Just the part of Ende.FileInfo that is required to calculate an `ETag`, so partial or user generated file information can be passed.
  • getCookies — Parse cookies of a header
  • getSetCookies — Parse set-cookies of a header
  • ifMatch — A helper function that takes the value from the `If-Match` header and a calculated etag for the target. By using strong comparison, return `true` if the values match, otherwise `false`.
  • ifNoneMatch — A helper function that takes the value from the `If-None-Match` header and a calculated etag for the target entity and returns `false` if the etag for the entity matches the supplied value, otherwise `true`.
  • InformationalStatus — An HTTP status that is a informational (1XX).
  • isClientErrorStatus — A type guard that determines if the status code is a client error.
  • isErrorStatus — A type guard that determines if the status code is an error.
  • isInformationalStatus — A type guard that determines if the status code is informational.
  • isRedirectStatus — A type guard that determines if the status code is a redirection.
  • isServerErrorStatus — A type guard that determines if the status code is a server error.
  • isStatus — Returns whether the provided number is a valid HTTP status code.
  • isSuccessfulStatus — A type guard that determines if the status code is successful.
  • Os — The OS as described by a user agent string.
  • RedirectStatus — An HTTP status that is a redirect (3XX).
  • serveDir — Serves the files under the given directory root (opts.fsRoot).
  • ServeDirOptions — Interface for serveDir options.
  • serveFile — Resolves a Response with the requested file as the body.
  • ServeFileOptions — Options for serveFile.
  • ServerErrorStatus — An HTTP status that is a server error (5XX).
  • ServerSentEventMessage — Represents a message in the Server-Sent Event (SSE) protocol.
  • ServerSentEventParsedMessage — A server-sent event message parsed from a stream.
  • ServerSentEventParseStream — Transforms a byte stream of server-sent events into parsed message objects.
  • ServerSentEventParseStreamOptions — Options for ServerSentEventParseStream.
  • ServerSentEventStream — Transforms server-sent message objects into strings for the client.
  • setCookie — Set the cookie header properly in the headers
  • STATUS_CODE — Contains the STATUS_CODE object which contains standard HTTP status codes and provides several type guards for handling status codes with type safety.
  • STATUS_TEXT — A record of all the status codes text.
  • StatusCode — An HTTP status code.
  • StatusText — An HTTP status text.
  • SuccessfulStatus — An HTTP status that is a success (2XX).
  • UserAgent — A representation of user agent string, which can be used to determine environmental information represented by the string. All properties are determined lazily.