Routing & Middleware

Hoody Exec routes by file path: the directory tree under scripts/ is the routing configuration. There is no route table to maintain and no Express-style router to mount. Create a file at api/users/[id].ts and it serves a dynamic endpoint at /api/users/123.

---

File-based routing

Files map to URL paths using Next.js-style patterns:

scripts/default/1/api/hello.ts        → GET /api/hello
scripts/default/1/users.ts            → GET /users
scripts/default/1/api/users/[id].ts   → GET /api/users/123
scripts/default/1/docs/[...slug].ts   → GET /docs/api/guide/intro

Hoody Exec derives these mappings from the directory layout, together with any middleware placed beside the route files.

---

Instance directories

Scripts live in instance directories. Each instance has its own hostname and an isolated script namespace.

File storage (instance directory):

/hoody/storage/hoody-exec/scripts/default/1/api/users/[id].ts
                                  └──┬──┘ └┬┘
                               Subdomain  Instance

The default segment is the subdomain namespace. It is the literal string default for a hostname with no subdomain in front of the project ID, which covers every URL on this page. A request to myapp.PROJECT_ID-CONTAINER_ID-exec-1... resolves under scripts/myapp/1/ instead.

URL paths (no subdomain or instance prefix):

GET /api/users/123  → executes scripts/default/1/api/users/[id].ts
GET /users          → executes scripts/default/1/users.ts
GET /docs/api/guide → executes scripts/default/1/docs/[...slug].ts

The instance ID (1, 2, test, and so on) appears in the hostname and in the storage path, but not in the URL:

• Hostname: exec-1, exec-2, exec-test
• Storage path: scripts/default/1/, scripts/default/2/, scripts/default/test/
• URL path: /api/users, never /1/api/users

Access URLs:

https://PROJECT_ID-CONTAINER_ID-exec-1.SERVER.containers.hoody.com/api/hello
https://PROJECT_ID-CONTAINER_ID-exec-2.SERVER.containers.hoody.com/users/123
https://PROJECT_ID-CONTAINER_ID-exec-test.SERVER.containers.hoody.com/docs/api/guide

Tip

Use multiple instances to keep concerns apart: exec-1 for your main API, exec-2 for webhooks, exec-test for development.

---

Dynamic route patterns

Hoody Exec supports Next.js-style dynamic routing with brackets:

Single parameter [param]

scripts/default/1/users/[id].ts → /users/123

The value arrives as metadata.parameters.id: "123".

Multiple parameters [param1]/[param2]

scripts/default/1/blog/[year]/[month].ts → /blog/2024/11

The values arrive as metadata.parameters.year ("2024") and metadata.parameters.month ("11").

Catch-all [...slug]

Matches one or more path segments:

scripts/default/1/docs/[...slug].ts → /docs/api/guide/intro

The segments arrive as an array in metadata.parameters.slug: ["api", "guide", "intro"].

scripts/default/1/docs/[...slug].ts

const parts = metadata.parameters.slug; // ["api", "guide", "intro"]
const fullPath = parts.join('/');       // "api/guide/intro"
return { section: parts[0], path: fullPath };

Caution

A catch-all needs at least one segment, so /docs on its own does not match docs/[...slug].ts. Use an optional catch-all ([[...slug]]) when the bare prefix has to match too.

Optional catch-all [[...path]]

Matches zero or more path segments, including the bare prefix:

scripts/default/1/pages/[[...path]].ts → /pages OR /pages/about OR /pages/blog/post/1

The segments arrive as metadata.parameters.path: [], ["about"], or ["blog", "post", "1"].

scripts/default/1/pages/[[...path]].ts

const parts = metadata.parameters.path; // [] for /pages, ["about"] for /pages/about
if (parts.length === 0) {
  return { page: "index" };            // Bare /pages
}
return { page: parts.join('/') };       // /pages/about → "about"

---

Pattern reference

Pattern	File path	Matches	Parameters
Static	scripts/default/1/api/hello.ts	/api/hello	{}
Index	scripts/default/1/api/index.ts	/api	{}
Dynamic	scripts/default/1/users/[id].ts	/users/123	{ id: "123" }
Nested dynamic	scripts/default/1/blog/[year]/[month].ts	/blog/2024/11	{ year: "2024", month: "11" }
Catch-all	scripts/default/1/docs/[...slug].ts	/docs/api/guide/intro	{ slug: ["api", "guide", "intro"] }
Optional catch-all	scripts/default/1/pages/[[...path]].ts	/pages or /pages/about	{ path: [] } or { path: ["about"] }

Note

The two catch-all forms differ at the prefix: [...slug] requires at least one segment after it and fails on /docs alone, while [[...path]] also matches the bare prefix and returns { path: [] } for /pages.

---

Dynamic directory segments

Dynamic parameters can appear in directory names, not only in file names. That is how you build nested REST-style resource paths:

scripts/default/1/users/[userId]/settings.ts           → /users/42/settings
scripts/default/1/users/[userId]/posts/[postId].ts     → /users/42/posts/99
scripts/default/1/shops/[shopId]/products/[productId].ts → /shops/abc/products/xyz

scripts/default/1/users/[userId]/posts/[postId].ts

const { userId, postId } = metadata.parameters;
// userId = "42", postId = "99"
const post = await db.getPost(userId, postId);
return { post };

---

File extensions

• Hoody Exec runs both .ts (TypeScript) and .js (JavaScript) scripts
• TypeScript is transpiled automatically, so there is no build step
• URL paths can include or omit the file extension: /api/hello and /api/hello.ts both resolve
• index.ts (or index.js) files match the directory root: api/index.ts handles /api

---

Route priority

When multiple files could match a URL, Hoody Exec uses this priority order:

1. Exact match: api/users.ts beats api/[param].ts for /api/users
2. Dynamic segments: api/[id].ts beats api/[...slug].ts for /api/123
3. Catch-all: api/[...slug].ts catches everything else
4. Optional catch-all: api/[[...path]].ts is the lowest priority fallback

Route collisions

Two dynamic route files at the same directory level ([id].ts and [slug].ts, for example) compete: the first match in filesystem order wins, and that order is not deterministic.

scripts/default/1/products/[id].ts      ← These compete for /products/abc
scripts/default/1/products/[slug].ts    ← Filesystem order determines winner

Caution

When you need different parameter names for the same position, give them distinct path prefixes instead of competing patterns in one directory:

scripts/default/1/products/by-id/[id].ts     → /products/by-id/123
scripts/default/1/products/by-slug/[slug].ts → /products/by-slug/cool-widget

---

Middleware

Hoody Exec supports pre/post middleware in both worker and serverless mode. A pre.ts and a post.ts run around any request that matches a script in the same directory as the middleware files.

Execution order: pre.ts → main script → post.ts

pre.ts, before the request

scripts/default/1/api/pre.ts

// @mode worker

// Authentication check
if (!req.headers.authorization) {
  res.statusCode = 401;
  return { error: "Unauthorized" }; // Early exit: main script skipped
}

// Validate token and add to shared
const userId = validateToken(req.headers.authorization);
shared.currentUser = { userId, timestamp: Date.now() };

// Return nothing to continue to main script

Behavior in pre.ts:

• Runs before requests matching a script in the same directory (api/)
• Return a value to short-circuit (skip main script)
• Return nothing (or undefined) to continue to main script
• Can set shared properties for the main script to use

Main script

scripts/default/1/api/users.ts

// Your regular endpoint script (same directory as pre.ts/post.ts)

const users = await db.getUsers();
return { users };

post.ts, after the request

scripts/default/1/api/post.ts

// @mode worker

// mainResult contains the main script's return value (concurrency-safe)
return {
  success: true,
  data: mainResult,
  user: shared.currentUser?.userId,
  timestamp: new Date().toISOString(),
  version: "1.0.0"
};

Behavior in post.ts:

• Runs after requests matching a script in the same directory (api/)
• mainResult contains the return value from the main script
• Return a new value to replace or wrap the main script’s response
• Runs even when pre.ts short-circuits, so logging, cleanup, and response envelopes still happen

Note

Middleware belongs next to the routes it wraps, in the same directory as the matched script, and it runs in both worker and serverless mode.

Middleware discovery

When a request matches a script, Hoody Exec looks for a pre.ts and a post.ts in the same directory as the matched script file. Either extension works (.js or .ts), and TypeScript is tried first. The middleware files apply to the routes in their own directory.

scripts/default/1/api/users/pre.ts       ← Runs before scripts in api/users/
scripts/default/1/api/users/[id].ts      ← Main script executes
scripts/default/1/api/users/post.ts      ← Runs after, receives mainResult

Execution order: pre.ts → main script → post.ts. Discovery does not walk up the directory tree: pre.ts and post.ts apply only to scripts in the directory that contains them. To wrap an entire instance, place the matched scripts and their pre.ts/post.ts in the same directory.

post.ts receives the main script’s return value in mainResult. It runs even when pre.ts short-circuits by returning a value, so it can still log, clean up, or reshape the response.

Note

pre.ts, the main script, and post.ts run in both modes and share the same shared object within a single request, so pre.ts can stash data the main script reads back. What differs is lifetime: in worker mode shared persists across requests, while in serverless mode it resets per request and stays consistent only within that one request’s pre→main→post chain.

---

Route API endpoints

Hoody Exec exposes its router over HTTP for programmatic route management:

Route resolution

Determine which script handles a given URL path:

CLI

# Resolve which script handles a URL path
hoody exec routes resolve --body '{"path":"/api/users/123"}' -c CONTAINER_ID -o json

SDK

const containerClient = await client.withContainer({
  id: CONTAINER_ID, project_id: PROJECT_ID, server: SERVER
});
const result = await containerClient.exec.route.resolve({
  path: '/api/users/123'
});
console.log(result.data); // { matched: true, path: "/api/users/123", hostname: "...", execId: "1", triedDirectories: [...] }
//                       (a miss returns { matched: false, path, hostname, execId, triedDirectories })

HTTP

curl -X POST "https://PROJECT_ID-CONTAINER_ID-exec-1.SERVER.containers.hoody.com/api/v1/exec/route/resolve" \
  -H "Content-Type: application/json" \
  -d '{"path": "/api/users/123"}'

URL

?

One request, one link

cURL runs inside your container and can wrap any HTTP request into a single GET URL. The call stops being something you need a client for and becomes something you can paste into a browser, send in a chat, bookmark, schedule with cron, or drop into a no-code tool.

Nothing is installed on the machine that opens it. The link does carry whatever credentials the call needs, so treat it as you would treat those credentials.

Slashes, colons and braces pass through as they are. The one character you must encode is an & inside a value, which happens when the wrapped URL carries its own query string. Left raw it ends the value early, and the rest is read as cURL's own parameters, so you get a 200 on a request you did not make.

How the wrapping works Chaining calls into one link Turning a link into a shortcut

Resolves which script would handle this path, without actually invoking it.

Copy

https://PROJECT_ID-CONTAINER_ID-curl-1.SERVER.containers.hoody.com/api/v1/curl/request?url=https://PROJECT_ID-CONTAINER_ID-exec-1.SERVER.containers.hoody.com/api/v1/exec/route/resolve&method=POST&json={"path":"/api/users/123"}&response=transparent

Route discovery

List all available routes in an instance:

CLI

# Discover all routes in the exec instance
hoody exec routes discover -c CONTAINER_ID -o json

SDK

// Without baseDir, discovery scans the whole scripts root; scope it to this instance.
const routes = await containerClient.exec.route.discover({ baseDir: 'default/1' });
console.log(routes.data.routes); // [{ pattern: "/api/hello", file: "default/1/api/hello.ts", type: "static", parameters: [] }, ...]
// response shape: { baseDir, count, routes }

HTTP

curl -X POST "https://PROJECT_ID-CONTAINER_ID-exec-1.SERVER.containers.hoody.com/api/v1/exec/route/discover"

URL

?

One request, one link

cURL runs inside your container and can wrap any HTTP request into a single GET URL. The call stops being something you need a client for and becomes something you can paste into a browser, send in a chat, bookmark, schedule with cron, or drop into a no-code tool.

Nothing is installed on the machine that opens it. The link does carry whatever credentials the call needs, so treat it as you would treat those credentials.

Slashes, colons and braces pass through as they are. The one character you must encode is an & inside a value, which happens when the wrapped URL carries its own query string. Left raw it ends the value early, and the rest is read as cURL's own parameters, so you get a 200 on a request you did not make.

How the wrapping works Chaining calls into one link Turning a link into a shortcut

Lists every route the instance currently exposes, along with its file path, pattern type, and parameters.

Copy

https://PROJECT_ID-CONTAINER_ID-curl-1.SERVER.containers.hoody.com/api/v1/curl/request?url=https://PROJECT_ID-CONTAINER_ID-exec-1.SERVER.containers.hoody.com/api/v1/exec/route/discover&method=POST&response=transparent

Route testing

Test multiple URL paths against the routing system in a single batch:

CLI

# Test multiple paths against routes
hoody exec routes test --body '{"paths":["/api/users/123","/api/health","/nonexistent"]}' -c CONTAINER_ID -o json

SDK

const test = await containerClient.exec.route.test({
  paths: ['/api/users/123', '/api/health', '/nonexistent']
});
console.log(test.data);
// { tested: 3, matched: 2, notMatched: 1, results: [
//   { path: "/api/users/123", matched: true, scriptPath: "...", type: "dynamic", params: { id: "123" } },
//   { path: "/api/health", matched: true, scriptPath: "...", type: "static", params: {} },
//   { path: "/nonexistent", matched: false, scriptPath: null, type: null, params: {} }
// ]}

HTTP

curl -X POST "https://PROJECT_ID-CONTAINER_ID-exec-1.SERVER.containers.hoody.com/api/v1/exec/route/test" \
  -H "Content-Type: application/json" \
  -d '{"paths": ["/api/users/123", "/api/health", "/nonexistent"]}'

URL

?

One request, one link

cURL runs inside your container and can wrap any HTTP request into a single GET URL. The call stops being something you need a client for and becomes something you can paste into a browser, send in a chat, bookmark, schedule with cron, or drop into a no-code tool.

Nothing is installed on the machine that opens it. The link does carry whatever credentials the call needs, so treat it as you would treat those credentials.

Slashes, colons and braces pass through as they are. The one character you must encode is an & inside a value, which happens when the wrapped URL carries its own query string. Left raw it ends the value early, and the rest is read as cURL's own parameters, so you get a 200 on a request you did not make.

How the wrapping works Chaining calls into one link Turning a link into a shortcut

Tests a batch of paths against the routing table in one call and reports which ones match.

Copy

https://PROJECT_ID-CONTAINER_ID-curl-1.SERVER.containers.hoody.com/api/v1/curl/request?url=https://PROJECT_ID-CONTAINER_ID-exec-1.SERVER.containers.hoody.com/api/v1/exec/route/test&method=POST&json={"paths":["/api/users/123","/api/health","/nonexistent"]}&response=transparent

---

What’s next

Writing Scripts Script format, available variables, and response handling

Magic Comments Complete reference for all configuration comments

Execution Modes Worker and serverless modes compared, with examples

Routing API Reference API endpoints for route management and validation