Extend an Architect @http
function with a powerful request router.
Obelisk Arc is powered by find-my-way
- used by Fastify and Restify. Obelisk adopts route-matching from find-my-way
and maintains handler compatibility with @architect/functions
, specifically arc.http
.
Try the DEMO application.
Make sure you actually want a "fat function", then:
npm i obelisk-arc
Requires Node.js v18+ (v16 works, but isn't recommended).
Not tested in a live CommonJS Node Lambda.
src/http/any-some-catchall/index.mjs:
import arc from "@architect/functions";
import Router from "obelisk-arc";
const router = new Router();
router.on(
"GET",
"/things/near/:lat-:lng/radius/:r",
async ({ routeParams, query }) => {
const { lat, lng, r } = routeParams;
const { foo } = query;
// do something with route and query params
return {
json: { routeParams, query },
};
},
);
export const handler = arc.http(router.mount());
A more elaborate router can be found in ./example/src/http/any-catchall/index.mjs
Deploy with Architect -- see ./example
for a sample Arc project.
Create a new Obelisk router.
Specify a default handler that will be invoked when no route is matched or a matched route does not return.
function defaultRoute ({ method, path }) {
// event and context are always available
// params, searchParams, and store are only available if a route was matched
console.log("defaultRoute", method, path);
return {
statusCode: 404,
text: "not found.",
};
}
const router = new Router({ defaultRoute });
Add a route to a router instance. See find-my-way
's docs on method
and path
.
Note that handler functions are mostly Architect Functions handlers. See Handlers API below.
router.on("GET", "/things/:id", ({ routeParams }) => {
const { id } = routeParams;
return {
statusCode: 200,
headers: { "content-type": "application/json" },
body: JSON.stringify({ thingId: id }),
};
});
Mount to router to Architect's http
helper which is in turn returned as the Lambda handler.
import arc from "@architect/functions";
import Router from "obelisk-arc";
const router = new Router();
router.on(
"GET",
"/",
async () => {
return { text: "hello, world" };
},
);
export const handler = arc.http(router.mount());
Describe the path where the router is mounted. Use a leading slash; omit a trailing slash.
router.mount({ rootPath: "/api" })
See ./example/src/any-api-catchall/index.mjs
for a simple example.
See ./example/src/get-thing-000id-catchall/index.mjs
for an example combining Arc path params
and Obelisk routeParams
These are mostly used internally and likely not helpful to developers at runtime. They are exposed for debugging purposes.
The original defaultRoute
passed into the constructor.
A Map
of registered routes keyed by the value returned when registering a route.
The internal FindMyWay
router instance.
Note: provided route handlers are not actually registered with router.router
and are managed in router.handlers
.
The third argument when registering a route is the handler function. It must be async.
async function handler(request, context) { /*...*/ }
The request object provided by Architect Functions. It is unmodified except the addition of one key: routeParams
.
Reference: arc.http
Requests
arc.http
already uses the params
key to express Architect route parameters, so routeParams
is added to track parameters from the Obelisk Arc router as they are parsed by find-my-way
This is the only modification made to the request
payload.
router.on(
"GET",
"/things/near/:lat-:lng/radius/:r",
async ({ routeParams }) => {
const { lat, lng, r } = routeParams;
const thing = await things.geoFind({ lat, lng }, r);
return {
statusCode: 200,
headers: { "content-type": "application/json" },
body: JSON.stringify({ thing }),
};
},
);
Reference: AWS Lambda context object in Node.js
Why rely on Architect + arc.http()
?
- Arc Functions provides a ton of valuable parsing: sessions, body, query, etc.
- There's a more vanilla flavor:
obelisk-lambda
, if you'd like to remove that peer dependency
Also, technically, you can use @architect/functions
without @architect/architect
in a Lambda.
defaultRoute
isn't getting some `routeParams`, what gives?
If the original request doesn't match a route, defaultRoute
is invoked with the original request
from Arc Functions and the Lambda context
args.