Socket Authentication

Authenticating web socket connections is crucial for securing real-time applications. Hyper-fetch provides a straightforward way to handle socket authentication by passing credentials through query parameters during the initial connection handshake. This guide will walk you through the process of setting up and managing authentication for your socket connections.

What you'll learn

1. How to provide initial authentication data using query parameters when creating a socket instance.
2. How to dynamically update authentication details for a live socket connection.
3. How Hyper-fetch automatically handles reconnection when authentication data changes.

---

Authentication via Query Parameters

The most common way to authenticate a WebSocket connection is by including a token in the connection URL's query parameters. Hyper-fetch makes this straightforward with the queryParams option in the Socket constructor.

import { Socket } from "@hyper-fetch/sockets";

const token = "your-initial-auth-token";

const socket = new Socket({
  url: "ws://localhost:8080",
  queryParams: { token },
});

socket.onConnected(() => {
  console.log("Socket connected with token!");
});

socket.onDisconnected(() => {
  console.log("Socket disconnected");
});

The queryParams are appended to the connection URL, so the server receives them during the WebSocket handshake and can verify the client's identity before accepting the connection.

---

Dynamic Authentication Updates

Authentication tokens can expire or change during the application's lifecycle. Hyper-fetch allows you to update the connection credentials using the setQueryParams method.

When you call setQueryParams with new data, Hyper-fetch will automatically disconnect the current socket and reconnect with the updated query parameters.

import { Socket } from "@hyper-fetch/sockets";

const socket = new Socket({
  url: "ws://localhost:8080",
  queryParams: { token: "initial-token" },
});

socket.onConnected(() => {
  console.log("Socket connected!");
});

socket.onDisconnected(() => {
  console.log("Socket disconnected");
});

// Later in your application, when you receive a new token
const updatedToken = "your-new-auth-token";

socket.setQueryParams({ token: updatedToken });

This triggers an automatic reconnection with the new token. The seamless reconnection ensures that your application maintains a valid authenticated session without manual intervention.

---

Authentication via Adapter Options

For adapters that support it (like Socket.IO), you can pass authentication data through adapterOptions which maps to the adapter's native connection options:

import { Socket } from "@hyper-fetch/sockets";

const socket = new Socket({
  url: "ws://localhost:8080",
  adapterOptions: {
    auth: { token: "your-auth-token" },
  },
});

This is adapter-specific - check your adapter's documentation for supported authentication options.

---

Congratulations!

You now know how to handle authentication in Hyper-fetch sockets.

• You can provide initial authentication credentials using queryParams or adapterOptions.
• You can dynamically update authentication data with the setQueryParams method, which triggers a reconnection.
• You understand that changing query parameters triggers an automatic reconnection with the new credentials.