HarperFast / HarperFast/harper
[Core] No supported way for a component to declare it serves REST resources (forces boot-order hacks)
- Dominant language
- JavaScript
- Stars
- 89
- Forks
- 10
- Avg merge
- 2d 6h
- Merged PRs (30d)
- 200
Description
Surfaced while making the `/v1` models gateway (#631) a clean plugin, from @kriszyp's review on #1616.
## Problem
A component that registers REST-served resources has no supported way to ensure REST is actually serving. `defaultConfig.yaml` ships **no** `rest` section, and REST's middleware chain only activates when some config declares `rest`/`REST`. So on a bare instance (no apps), a core/built-in component can register resources that are silently unservable.
#1616 worked around this by reaching into core twice — a `componentLoader` branch naming the feature by hand, plus a new exported `REST.ensureStarted()`. Both have been removed (the gateway now documents that it requires a `rest` section), but the underlying gap remains and the next component to hit it will be tempted by the same hack.
## Why the naive fix is wrong
Forcing REST to start early is not just a layering smell — it's incorrect. The activation ran after *root* plugins but **before `loadComponentDirectories()`**, which is where application configs load. `REST.handleApplication` sets `httpOptions` then hits `if (started) return`, so once something has force-started REST, a later app's own `rest` options are silently discarded:
- `rest: { webSocket: false }` ignored (ws already registered)
- `urlPath` / `host` restrictions not applied to the shared dispatcher
- middleware ordering via `before: 'rest'` / `after: 'rest'` cannot be expressed against that listener
So any mechanism here must defer activation until the *effective* REST options are known — i.e. after application directories load — while still retaining a stable `rest` middleware name.
## Ask
A first-class way for a component to declare "I serve REST resources; ensure REST is active", resolved after app load with the effective options. Shape is open — a scope-level declaration, a dependency/capability the loader resolves, or an explicit ordering hook.
Related: whether such a component's resources belong in the shared `resources` registry at all, or should be provided as scoped/custom resources (@kriszyp raised this on #1856).
Context: #631 (Phase 4 of #510), #1616.
🤖 Filed with [Claude Code](https://claude.com/claude-code) on behalf of @heskew
Contributor guide
Research direction
Start by tracing the componentLoader flow through loadComponentDirectories() and the REST.handleApplication entry point, then inspect defaultConfig.yaml and the existing REST activation behavior. Confirm when application options become effective and how middleware ordering is represented. Done means a documented, supported declaration can activate REST after app loading without discarding later REST options.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, node.js
- Domain
- api, backend
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100