Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Ensure every response carries consistent, documented headers that clients and tools can rely on

Open
  • Is something wrong?
#289 1 comment 0 reactions 0 assignees View on GitHub

@ranjeet150 is already working on this.

Since Oct 9, 2026.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
25/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
nodejs, typescript
Domain
api, documentation

Research direction

Start in src/config/cors.config.ts, where exposedHeaders lists only X-Total-Count and allowedHeaders lacks any request-id header. The issue first asks for a header contract to be decided and written in docs/, and it depends on the request-id and rate-limit issues, so confirm those decisions before editing. Done means the contract is documented, the headers appear in docs/openapi.json via @ApiHeader, and a CORS test shows a browser client can read the correlation and rate-limit headers.

Written by the indexing model from the issue text.

Description

accessibility documentation good first issue

Problem

Clients — SDKs, dashboards, monitoring agents, and the operator UIs the README describes — can only act on information they can reliably find in responses. Several such headers are missing, inconsistent, or undocumented:

  • src/config/cors.config.ts exposes only one: exposedHeaders: ["X-Total-Count"]. So X-RateLimit-* and Retry-After are not exposed to browser clients even if the server sets them — meaning a dashboard in a browser cannot implement throttling.
  • allowedHeaders is ["Content-Type", "Authorization", "X-Requested-With"], so a client cannot even send an X-Request-Id for correlation.
  • There is no X-Request-Id on responses at all, so a user reporting a problem cannot quote an id that maps to server logs.
  • x-powered-by is disabled (good), but the CORS X-Requested-With allowance is not obviously serving a purpose.

Why it matters

This is the API equivalent of a page with no labels: the information exists on the server, but the client has no documented, reliable way to reach it. For the operator dashboard in particular — the README's "Real-time agent dashboard" is a first-class feature — throttling and correlation headers being unreachable from the browser means the dashboard cannot show useful diagnostics.

Suggested Direction

  1. Decide the header contract and document it. Reasonable set: X-Request-Id, the X-RateLimit-* family, Retry-After, X-Total-Count, and Deprecation/Sunset if the deprecation issue lands.
  2. Expose them all in cors.config.ts exposedHeaders so browser clients can read them.
  3. Allow correlation headers in allowedHeaders so a client can propagate its own id — validate the format before echoing it, as the request-id issue specifies.
  4. Add X-Request-Id to every response (interceptor or middleware).
  5. Document them in docs/ and mark them with @ApiHeader decorators so they appear in the OpenAPI spec and generated SDKs.
  6. Consider removing X-Requested-With from allowedHeaders if nothing uses it — every unnecessary allowed header is extra surface.

Constraints

  • Do not expose internal headers that leak configuration. Headers are readable by any browser client once exposed.
  • Header names and values must not contain user input unsanitised, particularly X-Request-Id.
  • Changing allowedHeaders/exposedHeaders is a client-visible change — note it in CHANGELOG.md.
  • Coordinate with the rate-limit-headers issue so the contract is defined once.

Acceptance Criteria

  • A documented header contract exists in docs/.
  • All contract headers are listed in exposedHeaders.
  • X-Request-Id is returned on every response and accepted on inbound requests when valid.
  • Rate-limit headers are readable by browser clients.
  • Headers are marked with @ApiHeader and appear in docs/openapi.json.
  • A test asserts a browser client can read the correlation and rate-limit headers under CORS.
Dominant language
TypeScript
Stars
7
Forks
55
Avg merge
1d 17h
Merged PRs (30d)
5

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from SourceXXL/alian_structure-api

All issues in SourceXXL/alian_structure-api

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.