Skip to main content
Version: Next

Cookie syncing

Cookie syncing keeps document.cookie and the server-side socket.cookies map aligned without any manual fetch logic. The flow is automatic once the client bundle is loaded.

How it works​

  1. Handshake – every WebSocket upgrade issues an HttpOnly zilaSession cookie. The server stores the same token against the ZilaClient instance.
  2. Sync trigger – when you change socket.cookies on the server (or the browser mutates document.cookie), the client runtime calls GET /zilaws/cookieSync.
  3. Merge – the server reconciles values for the shared session and responds with any missing cookies so the browser stays in sync.

ℹ️ The zilaSession cookie is managed by ZilaWS. Attempts to change or delete it on the server are ignored.

Server-side usage​

Use the exposed map on each ZilaClient to read and write cookies:

server.setMessageHandler("Login", async (client, token: string) => {
  client.cookies.set("authToken", token); // Browser receives Set-Cookie automatically
});

server.setMessageHandler("Logout", (client) => {
  client.cookies.delete("authToken");
});
  • Prefer server-side writes so that authentication and session state remain authoritative.
  • The map only exposes get, set, delete, has, and iterators. Other mutations are intentionally blocked.

  • Restrict cookieSyncAllowedOrigins when hosting the sync endpoint on a shared domain:

    const server = new ZilaServer({
      port: 6589,
      cookieSyncAllowedOrigins: ["https://app.example.com"],
    });

  • Enable HTTPS so the issued cookies gain the Secure attribute.

  • Keep browser logic simple: just load the latest ZilaWS client bundle—no custom polling required.

With these basics in place, you get a single source of truth for cookies, reliable session tracking, and automatic propagation of any values you set on the server.