Achieve — High Level Logic Project. Creating a new meta design pattern.

Friendly in development. Fast in production. Just build your apps. Let Achieve do the rest.

← Back to documentation index

Configuration

Before starting a listener, use setAppPath() to choose the application space containing the resources achieve will make available through HTTP. Achieve does not supply a default application space. Other configuration methods select optional behavior. Example startup with configurations:

const achieve = require("achieve");

achieve.setAppPath("C:/projects/myApplication/public");
achieve.setMode("production");
achieve.setCaching(true);
achieve.setCompress(true);
achieve.setLogging("server", "access");

achieve.listen(8989);
Table 1: List of configuration options and defaults
Method name Short description Default
addAVMimeType()Add an audiovisual MIME type.built-in AV MIME table
addMimeType()Add an ordinary MIME type.built-in MIME table
allowOrigins()Permit cross-origin access.none
registerMethod()Register an additional HTTP method.GET, HEAD, POST, OPTIONS
setAppPath()Set the public application root.none
setBufferedInputLimit()Set maximum buffered POST input.1 MiB (1024 × 1024)
setCaching()Enable browser caching and HTTP validators.false
setCompress()Compress eligible static resources.false
setLogging()Select logging options.no persistent logging
setLogPath()Set the log directory.[achieve install/startup directory]/logs/
setMode()Set Achieve mode: "development" or "production"."development"
setNodeEnv()Set NODE_ENV."production" if NODE_ENV is undefined
setPathMap()Add subtree mappings.none
setRouteMap()Add exact resource mappings.none
showMimeTypes()Show MIME types at startup.off

addAVMimeType() - Add an audiovisual MIME type to the AV MIME list

(See also showMimeTypes().)

Add a media type that should use Achieve's audiovisual streaming and range-request handling with:

achieve.addAVMimeType("wav", "audio/wav");

The leading dot is optional.

addMimeType() - Add a MIME type to the MIME list

(See also showMimeTypes().)

Add an ordinary static MIME type with:

achieve.addMimeType("pub", "application/x-mspublisher");

The leading dot is optional:

achieve.addMimeType(".pub", "application/x-mspublisher");

The .jss suffix is reserved for protected server-side servlet source and cannot be registered as a public MIME type.

allowOrigins() - set CORS permissions

default: no CORS permissions granted

Browsers normally restrict requests from one origin to another. allowOrigins() configures the origins that may access selected application resources.

Allow one origin to access all assets beneath /api/:

achieve.allowOrigins(
    "https://example.com",
    "/api/",
    "*"
);

Restrict permission to named assets:

achieve.allowOrigins(
    "https://example.com",
    "/downloads/",
    ["catalog.json", "current.zip"]
);

Origins, paths, and asset names may also be supplied as arrays:

achieve.allowOrigins(
    [
        "https://www.example.com",
        "https://admin.example.com"
    ],
    ["/api/", "/reports/"],
    "*"
);

If paths and assets are omitted, they default to "*", granting that origin access throughout the application space:

achieve.allowOrigins("https://example.com");

The "*" wildcard may also be used for origins. Grant all origins access throughout the application space:

achieve.allowOrigins("*");

Calls accumulate policies for different origins and paths. For an incoming origin, achieve first selects its exact-origin policy map when one exists. The "*" origin policy map is used only when no exact-origin map exists; permissions from the two maps are not combined. Within the selected map, the most-specific matching path policy takes precedence, allowing access to be narrowed to particular directories or assets.

A later call for the same origin and path replaces the previous policy for that combination.

For an approved cross-origin request, achieve returns the corresponding Access-Control-Allow-Origin response header. A cross-origin request without matching permission is refused with a 403 response.

registerMethod() - register a custom implementation of an HTTP method

GET, HEAD, POST, and OPTIONS are implemented by Achieve. Other valid HTTP methods, standard or non-standard, can be registered with your own implementation. CONNECT is reserved for server-level handling and cannot be registered as an application method.

Registration uses method name and path to implementing servlet.

Example:

achieve.registerMethod(
    "PURGE",
    "methods/purge.jss"
);

Method names for standard methods must be valid HTTP method tokens and must not be one of achieve’s implemented or reserved methods. The servlet path is relative to the application space and must identify a supported servlet file:

A request using the registered method invokes that servlet. The servlet receives the normal session request and response objects and can inspect the requested target.

A method name can be registered only once.

setAppPath() - set the public application space

The application path is the top of the directory tree of the public application space. Achieve restricts HTTP request path resolution to resources within the application space. Incoming URI request paths are resolved from the app path.

You can set your application space to anywhere the computer can access.

achieve.setAppPath("C:/projects/myApplication/public");

Now a request to http://localhost:8989/myapp/ will be routed to C:/projects/myApplication/public/myapp/.

TIP: To create a refactoring-friendly private area, reached only from your servlets, use the session.appPath parameter in the servlet.

let private = path.resolve(session.appPath, "../private");

setAppPath() changes the application space. It does not change the startup directory or the default location of log files.

Routing, exact route mappings, and subtree mappings are covered in detail on the Routing page.

setBufferedInputLimit() - set the limit on request data size that achieve will parse before delivery to the servlet

Default: 1 MiB

Parsed data is made available through the servlet session object as session.params. The following explains when achieve parses input data. TIP: For large uploads, avoid parsing and let the servlet handle the data stream via the session.request object.

GET query-string data is always parsed.

Achieve buffers and parses POST bodies with these content types:

For compatibility, a POST without Content-Type is treated as application/x-www-form-urlencoded. Achieve emits a server warning: to the development console in development mode, and to the persistent server log in production when server logging is enabled.

If buffered input exceeds the configured limit, achieve responds with 413 Payload Too Large and does not invoke the servlet.

Change the input limit with:

achieve.setBufferedInputLimit(2 * 1024 * 1024);

The value must be a positive safe integer and must remain within achieve's memory-safety limit for the current Node process.

setCaching() - toggles support for static resource browser caching

Default: false. Achieve does not normally send ETag and Last-Modified validators. Enabling caching adds these validators to static and media responses, allowing browsers to revalidate cached resources.

Enable it with:

achieve.setCaching(true);

When enabled, achieve supplies ETag and Last-Modified validators for static and media resources. Achieve supports conditional requests using If-Match, If-Unmodified-Since, If-None-Match, and If-Modified-Since. Successful cache validation for GET and HEAD can produce 304 Not Modified; failed preconditions produce 412 Precondition Failed where applicable.

Disable it explicitly with:

achieve.setCaching(false);

Disabling caching stops the normal advertisement of validators, but it does not disable all conditional-request processing. Preconditions supplied by a client can still affect a response. See the Static Resources Reference for details.

setCompress() - compress static assets support

Browsers and other clients may request that the server compress responses and provide a list of preferred compression algorithms.

Default: false, compression not supported

Enable it with:

achieve.setCompress(true);

When compression is enabled, achieve can serve gzip or deflate representations of text and application static resources when the client advertises support for them. Achieve generates and maintains its own artifacts beneath .compression-cache in the application space; it does not use conventional adjacent precompressed sidecar files.

When a compressed representation is not already available, Achieve creates it asynchronously, so the first request may receive the uncompressed resource. Later requests can use the compressed representation.

See the Static Resources Reference for representation selection, cache protection, and fallback behavior.

setLogging() - in startup file before call to listener

Default: no persistent logging

Development mode provides developer-friendly diagnostic output to the console. This is controlled by mode, not by setLogging(). Production mode does not produce development diagnostic output.

Options:

Log file location defaults (see also setLogPath()):

server and access: [startup directory]/logs/

Set either or both options by name:

achieve.setLogging("server", "access");

Use a boolean setting for both or none:

achieve.setLogging(true);  // server and access
achieve.setLogging(false); // no persistent logging

setLogPath() - select a path to log files

Default: [startup directory]/logs/

An absolute path selects that location directly:

achieve.setLogPath("c:/path/to/logs/");

A relative log path is resolved from the server startup directory, not from the application space:

achieve.setLogPath("./logs/"); // [startup directory]/logs/

setMode() development (default) to production

Achieve’s automatic servlet error checking and reporting work in both development and production. Achieve typically does not crash on servlet error. Error codes and messages are also returned in the http response. (See exception in servlet document.)

Development mode is the default, helping to provide achieve’s “friendly in development” nature.

achieve.setMode("development");

In development mode, changed servlets are automatically reloaded without restarting the server. Helper modules loaded with session.load() are also reloaded when changed. URL request information, diagnostics, and error reporting are sent to the console. (See also session.load() and setLogging().)

Production mode:

achieve.setMode("production");

Production mode reuses cached servlet and helper modules without reloading when changed. Application code changes become visible after the server restarts.

setNodeEnv() - set the Node environment

setNodeEnv() sets Node’s conventional NODE_ENV process environment variable:

default: achieve.setNodeEnv("production");

Achieve mode and NODE_ENV are separate settings:

achieve.setMode("production");
achieve.setNodeEnv("production");

setMode() controls achieve’s own development and production behavior. setNodeEnv() sets process.env.NODE_ENV for application code and packages that use that convention. Calling one does not automatically select the other. Achieve defaults NODE_ENV to production so that already tested third party modules that use the convention do not weigh down achieve application development with extra processing.

setPathMap()

setPathMap() maps one public directory subtree to another directory subtree inside the application space.

setPathMap() is part of the routing trio. See also setAppPath() and setRouteMap().

See the Routing reference for more details.

achieve.setPathMap({
    "/docs/": "/internal/documentation/"
});

Both paths must end in /. Additional calls accumulate mappings, and repeating the same public prefix replaces only that prefix.

Exact mappings take precedence over subtree mappings. When several subtree prefixes match, the longest matching prefix wins.

setRouteMap()

setRouteMap() maps a complete public resource path to a resource path inside the application space.

setRouteMap() is part of the routing trio. See also setAppPath() and setPathMap().

See the Routing reference for more details.

achieve.setRouteMap({
    "/short": "/internal/page.htm"
});

Additional calls accumulate mappings:

achieve.setRouteMap({
    "/status": "/servlets/status.jss"
});

Supplying the same public path again replaces only that mapping.

showMimeTypes() - Display the current list of supported MIME types

(See also addMimeType() and addAVMimeType().)

Strictly speaking, showMimeTypes() is not a configuration option. It displays the MIME types currently supported by Achieve. The MIME list is used to set the Content-Type header for assets being served.

Browsers use Content-Type to determine how content should be handled. Achieve takes care of setting it automatically as long as the file extension is included in the MIME list. If a MIME type is not set to a particular extension, it defaults to text/plain. The MIME list also includes servlet: text/plain. This is the default for servlet responses. Alternative Content-Types for servlet returns are typically set in the servlets themselves.

Additional MIME types can be registered using addMimeType() and addAVMimeType(), so you are not limited to the types initially supplied by Achieve.