Achieve Application-Space Routing
Created November 6, 2026 · Updated November 6, 2026 · Achieve 3.1.0 · Qualified runtime: Node.js 24.22.2
Achieve maps public request paths to static resources and JavaScript Servlets inside a configured application space. The application space is both the default routing root and the containment boundary for resources exposed through Achieve's HTTP routing.
Required application space
setAppPath() is required before a listener starts; Achieve does not select a default application directory. The path can be absolute or resolved from the startup process, but after configuration Achieve stores a canonical application root and refuses to start without it.
const achieve = require("achieve");
const path = require("node:path");
achieve.setAppPath(path.join(__dirname, "application"));
achieve.listen(8989);
With no custom mapping, a request path corresponds to the same relative path beneath that root. Directory handling, default documents, MIME selection, servlet execution, and media processing occur after the resource has been resolved.
Exact and subtree mappings
setRouteMap() maps one complete public path to one target path in the application space:
achieve.setRouteMap({
"/products": "/services/catalog/list.jss"
});
setPathMap() maps a public directory prefix to a directory subtree and preserves the remaining path:
achieve.setPathMap({
"/docs/": "/internal/documentation/"
});
When subtree mappings overlap, the longest matching public prefix wins. Definition order does not decide the result.
Precedence and processing
- exact route mapping;
- longest matching subtree mapping;
- automatic path routing.
A mapping changes location, not resource type. After translation, the target is processed normally according to its file type and configuration. A mapped servlet remains a servlet; a mapped static file remains static. The Node request object continues to expose the original public URL.
Containment and safety
Public paths and mapped targets are validated when configuration is supplied and again during resolution. Targets must remain beneath the application root. Achieve rejects traversal, invalid mapping forms, and resolved filesystem paths that escape through links or other physical path changes. The internal compression-cache area is not publicly routable, including through custom maps.
This HTTP boundary does not sandbox servlet code. A servlet is ordinary server-side Node.js code and can intentionally access other server resources using Node APIs and the permissions of the process.
Verification and limits
Routing, route-map, path-map, static lookup, servlet, compression-cache, request-path, and symlink cases verify precedence, longest-prefix behavior, file-type preservation, traversal rejection, and lexical and physical containment. Some symlink cases can be environmentally skipped on Windows where creating the required link is not permitted; Linux qualification runs them without those skips.
Routing maps are configured before listeners start and are not a dynamic middleware chain. Registered additional HTTP methods use their method-wide servlet handlers rather than normal URL routing.
For the complete public reference, see Routing and Configuration.
