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

Document the admin real-time channel (POST /_/realtime) and X-CWA-Client-Id

Closed
  • Is something wrong?
#294 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
67/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
typescript
Domain
backend-api-design, documentation

Research direction

Start in the bundle's content/4.api/ documentation and identify the endpoint and writer sections to update; check the linked bundle issue and PR for implementation details. Then find the template deployment guidance for Nelmio allow_headers and Mercure history settings. Done when the docs cover the endpoint behavior, payload, limits, writer echo, configuration, and deployment settings listed in this issue.

Written by the indexing model from the issue text.

Description

The bundle is adding an admin real-time channel (api-components-bundle#559, PR #560). Please document the following.

Bundle (content/4.api/)

  • Endpoint: POST /_/realtime (/_api/_/realtime under the template).
    • ROLE_ADMIN.
    • Body: {clientId, event, iri?, data?}, 16 KB at most.
    • Responds 202, and stores nothing.
  • Content types:
    • JSON accepts any event.
    • text/plain (navigator.sendBeacon) is accepted only for event: "presence" with data.state: "left".
    • Anything else is 415.
    • A cross-site request (Sec-Fetch-Site) is 403.
  • Payload, published privately on one site-wide topic that only admins' subscriber cookies grant:
    {"@type": "CwaRealtimeEvent", "v": 1, clientId, user: {id, name}, event, iri, data, sentAt, expiresAt}
  • Rate limits:
    • 20 burst / 10 a second per user and clientId.
    • 60 burst / 30 a second per user across all their clients.
    • Above either: 429 with Retry-After.
    • The limiter pool silverback.api_components.realtime.rate_limiter_cache uses cache.app by default, so the limits apply per pod. Point it at a shared adapter in framework.cache.pools to make them exact.
  • Publishing: bounded at 1 s. A failed or timed-out publish is logged and still answers 202.
  • Config: silverback_api_components.realtime.enabled (default true). When false, the endpoint is a 404 and no cookie grants the topic.
  • Writer echo: a write carrying X-CWA-Client-Id gets _metadata.lastWrite: {clientId, userId, at} in the writer's response and in the private ?draft=1 update.
    • at is server time, RFC 3339 with milliseconds.
    • Use at, not modifiedAt, to order draft updates.

Deployment

  • The front end must be allowed to send X-CWA-Client-Id. In the template, add it to nelmio's allow_headers. The bundle has no Flex recipe yet (#259).
  • Presence events stay in the Mercure hub's replay history, so mention the hub's history size and retention settings.
Dominant language
TypeScript
Stars
0
Forks
0
Avg merge
1h 20m
Merged PRs (30d)
1

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

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 components-web-app/docs

All issues in components-web-app/docs

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.