feat: typed HTTP errors with router-scoped error handling (Phase 6)

[dopry]

Summary

Phase 6 of the modernization roadmap: client errors stop masquerading as 500s.

The hierarchy (src/errors.ts)

• HttpError base carrying a statusCode; BadRequestError (400) and NotFoundError (404); the existing Unsupported{Platform,Channel,Tag}Error classes now extend BadRequestError.
• errorHandler() middleware translates HttpErrors into their status codes (JSON {error, code} or plain text via content negotiation) and logs a 500 fallback for everything else, with a headersSent guard.
• Registered at the end of the pecans router itself, so any host app composing pecans.router gets correct status codes with zero extra wiring. Also exported for host apps' own routes, and main() installs it as the app-level fallback.
• Moving the classes into src/errors.ts dissolves the long-standing pecans.ts ↔ versions.ts circular import; everything stays re-exported from the package root.

Status-code changes (error paths only)

Before	Now	Cases
500	400	unknown/invalid platform, invalid tag/semver range, missing update parameters, missing platform segment, unsupported filetype
500	404	unknown channel, version/release not found, missing RELEASES asset, /notes for an unknown version (previously crashed on undefined.notes)

The update handlers also gain early semver-range validation so a bad :version fails at the parameter boundary with attribution, instead of deep in release matching.

Squirrel contracts unchanged: 204/200 semantics, update JSON shape, and byte-exact RELEASES output are untouched — only failure paths moved, and Squirrel clients treat any non-2xx as "no update" either way. The Phase 1 contract tests for success paths pass unmodified; the ~14 tests that pinned 500s (several explicitly annotated "until typed error handling lands") now pin their intended 4xx codes.

Verification

• npm test: 31 files / 699 passed (5 new error-module tests); lint, typecheck, format, build all green.

🤖 Generated with Claude Code

https://claude.ai/code/session_015zUyj4PpSog9RkrYxzFRhM

---

Generated by Claude Code

[Copilot]

Pull request overview

This PR introduces a typed HTTP error hierarchy and a router-scoped Express error handler so Pecans’ client-caused failures return appropriate 4xx status codes instead of defaulting to 500s. It centralizes error translation/formatting in src/errors.ts, installs the middleware at the end of pecans.router, and updates unit/integration tests to match the new status-code behavior.

Changes:

• Add HttpError/BadRequestError/NotFoundError + errorHandler() middleware, and migrate existing “Unsupported*” errors onto this hierarchy.
• Update Pecans route handlers to throw typed errors (and forward to next) instead of writing ad-hoc 4xx/5xx responses.
• Update unit + integration tests to assert the new 400/404 behaviors and add dedicated middleware/hierarchy tests.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/errors.ts	Introduces typed HTTP errors and the shared Express error-handling middleware.
src/pecans.ts	Switches many failure paths to typed errors and installs router-scoped errorHandler().
src/versions.ts	Emits NotFoundError instead of generic Error when resolve finds no versions.
src/index.ts	Re-exports errors and installs errorHandler() as app-level fallback outside pecans.router.
test/unit/errors.spec.ts	Adds unit coverage for error types and errorHandler() behavior.
test/unit/pecans.spec.ts	Updates unit assertions to expect typed errors via next(err) and updated messages.
test/unit/versions.spec.ts	Updates imports to new error module location.
test/integration/update-win.spec.ts	Pins new 404 behavior for update failure paths.
test/integration/update-mac.spec.ts	Pins new 400 behavior for invalid platform/version/missing params.
test/integration/download.spec.ts	Pins new 400/404 behavior for invalid route/platform/no asset cases.
test/integration/dl.spec.ts	Pins new 404 behavior for unknown channel cases.
test/integration/api.spec.ts	Pins new 404 behavior for unknown release notes version.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (2)

src/pecans.ts:304

• serveAsset() is async; calling it without await means errors from the backend (or from serveAsset itself) will not be caught by this try/catch, so they won’t reach next(err) and won’t be translated by the router’s errorHandler(). This can surface as unhandled promise rejections under load or network failure.

        throw new NotFoundError("No Matching Assets Found");
      }

      const asset = matchingAssets[0];
      this.serveAsset(req, res, release, asset);
    } catch (e) {

src/pecans.ts:466

• This returns the Promise from serveAsset() without awaiting it, so any rejection from the backend can bypass this handler’s try/catch and won’t be forwarded to next(err) (Express 4 doesn’t automatically handle async promise rejections). Awaiting here ensures failures are consistently routed through errorHandler() instead of becoming unhandled rejections.

      if (!asset)
        throw new NotFoundError(
          `No download available for platform ${platform} for version ${release.version} (${channel})`,
        );

      // Call analytic middleware, then serve
      return this.serveAsset(req, res, release, asset);
    } catch (err) {
      next(err);
    }

[Copilot]

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.