HarperFast / HarperFast/skills
custom-resources: Document target routing, response patterns, and error handling
- Dominant language
- JavaScript
- Stars
- 3
- Forks
- 0
- Avg merge
- 3d 7h
- Merged PRs (30d)
- 8
Description
## Context
We built a Harper app with a single custom resource class handling ~30 API routes plus static file serving. The `custom-resources` rule explains how to create a resource class and map HTTP methods, but doesn't cover the routing and response mechanics we needed to figure out.
**Caveat:** Our patterns may be unconventional — we used a single resource with manual path routing rather than multiple resource classes. If Harper has a better idiomatic approach, the skill should show it.
---
### 1. `target` parameter and sub-path routing
**What we hit:** We needed to handle routes like `/myapp/api/users`, `/myapp/api/reports`, etc. Harper doesn't pass the full URL to the resource — it passes the sub-path after the resource prefix via a `target` parameter.
**What we did:** Wrote a helper to extract the path from `target` and used a series of `if (path === "/api/users")` conditionals. We couldn't find documentation on how `target` works, what properties it has, or whether Harper supports dynamic path segments (like `/api/users/:id`).
**What the skill should do:** Document what `target` is, what properties it exposes, and how to extract the request path. If Harper supports pattern-based routing or dynamic segments, show how. If the intended pattern is multiple resource classes (one per route), say that explicitly.
---
### 2. Returning custom status codes and headers
**What we hit:** We needed to return JSON responses with specific status codes (200, 403, 404, 409), set `Content-Type` headers, and set `Set-Cookie` headers for auth. The resource method signature and return type aren't documented.
**What we did:** Through experimentation, we found that returning a `Response` object works. We wrote `jsonResponse()`, `htmlResponse()`, and `redirect()` helpers. But we're not confident this is the intended pattern.
**What the skill should do:** Show how to return responses with custom status codes, headers (especially `Set-Cookie` as an array — comma-separated strings don't work), and different content types (JSON, HTML, binary).
---
### 3. Error handling in resources
**What we hit:** When our resource threw an unhandled exception, Harper returned a generic error that sometimes leaked internal details (stack traces, file paths). We weren't sure what the default error behavior was or how to control it.
**What we did:** Wrapped all route handlers in try/catch and returned sanitized error responses.
**What the skill should do:** Document what happens when a resource method throws (what status code? what body?), and show the recommended pattern for error handling. Even a simple "always catch errors and return a structured response" example would help.
---
### 4. Interaction between custom resources and static file serving
**What we hit:** Our resource class serves both API routes AND static files (HTML, CSS, JS) from the same URL prefix. We needed to understand the precedence: does `static.files` in config.yaml take priority, or does the custom resource?
**What we did:** Handled static file serving manually in our resource's GET handler, reading files from disk and setting appropriate content types. We're not sure if this was necessary or if we could have let Harper's static serving handle it.
**What the skill should do:** Clarify how custom resources and `static.files` interact on the same URL space. If they can coexist, explain the precedence rules.
Contributor guide
Assessment
This issue has not been assessed yet.