Realtime API

Realtime in Cortado

Cortado includes first-class support for WebSockets, enabling you to build realtime features directly within your backend. Whether you're streaming updates, syncing shared state, or building collaborative tools, the WebSocket layer uses the same routing structure and middleware patterns as HTTP — so there's no need to learn a separate system.

WebSocket routes are just .ws.ts files inside your routes/ directory, making it easy to manage REST and realtime side by side.

WebSocket Routing and Events

WebSocket connections in Cortado are persistent and bidirectional. When a client connects, it’s assigned a socket context and can begin sending or receiving events through structured channels.

Event messages typically follow a pattern:

• event — the name of the action

• payload — the data being sent

• room or channel — (optional) for scoped broadcasting

Cortado automatically parses incoming events and routes them to the appropriate handler inside your .ws.ts file. This makes real-time routing feel just as predictable as HTTP routes.

Securing Realtime Connections

Authentication applies to WebSockets just like HTTP. You can require a token in the initial handshake, validate it in connection middleware, and attach user data to the socket context.

Tip: Use the same token-based logic as your REST endpoints to ensure consistent auth across your app.

You can also restrict access to certain events based on user roles, project ownership, or even channel-based permissions. This ensures your real-time features remain secure and scoped.

Sending and Receiving Messages

Once authenticated, clients can send messages using structured JSON events, and receive broadcasts from the server or other users. Cortado supports broadcasting:

• To individual sockets

• To all sockets in a room

• To all connected clients

You can also emit system-level messages such as disconnects, errors, or status updates. These patterns make it easy to build features like live chat, presence indicators, shared boards, or multiplayer tools.

Event Logic and Scaling

Just like REST, WebSocket logic in Cortado can be abstracted into reusable handlers or services. You can organize event types, separate business logic, and compose responses dynamically.

For larger apps, you might:

• Namespace events by domain (chat:send, board:update)

• Use event queues or workers for heavy updates

• Sync real-time data with a persistent database in the background

This makes your WebSocket layer as maintainable and testable as your REST API.

Real-Time Without Complexity

Realtime development often feels intimidating — but Cortado simplifies it by making everything work in parallel with your existing API. There’s no separate server, no extra routing DSL, and no need to introduce external socket libraries unless you want to.

From prototypes to production-grade apps, Cortado’s WebSocket layer grows with you — and keeps your backend logic unified.