All jobs

Add Rate Limiting to a Socket.IO Chat Server

Yes. An agent adds a per-socket token bucket to your Socket.IO chat server, acks limited messages so the client stops retrying, tests it, and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads the message path end to end, because a rate limit sits in the middle of it. In a chat server like socketio/chat-example, package.json is an ES module depending on socket.io ^4.7.2, express ^4.18.2, @socket.io/cluster-adapter ^0.2.2, sqlite and sqlite3, with start as its only script and no development dependencies. index.js forks one worker per CPU from the cluster primary, each on PORT 3000 plus its index, and in each worker opens chat.db, creates a messages table with a unique client_offset, and creates the Server with connectionStateRecovery and the cluster adapter. The chat message handler inserts the message with its client offset, treats a unique-constraint error (errno 19) as a duplicate and acknowledges it, broadcasts with io.emit, and then calls the callback; on any other error it returns without acknowledging, on purpose, so the client retries.

The client side decides the shape of the limit. index.html creates the socket with ackTimeout: 10000 and retries: 3, builds a clientOffset from socket.id and a counter, and emits chat message with it. A message the server silently drops is therefore resent up to three times, which would turn a flood into a bigger flood. The limit has to acknowledge: Socket.IO stops retrying a packet once any ack arrives, so a limited message gets callback({ error: 'rate_limited', retryAfter }) and is neither stored nor broadcast, and the client, which today passes no callback, gets one that shows a short notice instead of appending the message.

The implementation is a token bucket per socket in server.js, which the agent splits out of index.js so the cluster wiring stays in index.js and the Express app, the Server and the handlers can be built in a test without forking. Each socket gets a bucket on connection, keyed by socket.id and removed on disconnect, with a capacity and a refill rate kept as constants read from the environment with defaults; the chat message handler takes a token before touching the database and acks the error when there is none. Because every socket lives on exactly one worker, a per-socket bucket needs no shared state across the cluster; a per-address limit across workers would, and the agent says so in the pull request rather than adding Redis to a project that has none. Replay on reconnect, the SELECT after a non-recovered connection, is not limited, since it sends history the server already accepted.

Tests come with the split. The agent adds socket.io-client as a development dependency and a test script running node --test; test/rate-limit.test.js starts one worker's app from server.js on port 0 with a temporary database file, connects a client, emits more messages in a burst than the bucket holds, and asserts the first ones ack cleanly and the last one acks with error: 'rate_limited', then waits for the refill and asserts a message goes through again; a second case checks a limited message was not broadcast to a second client. It runs npm install, npm test and node --check index.js, and starts index.js once to see every worker log its port.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add rate limiting to this Socket.IO chat server. Read package.json, package-lock.json, index.js, index.html, .gitignore and .codesandbox/Dockerfile first. Note that index.html sets ackTimeout and retries, so a silently dropped message is resent; a limited message must be acknowledged with an error payload and must not be stored or broadcast. Move the Express app, the Server and the connection handler from index.js into server.js with a function a test can call, keeping the cluster primary and worker wiring in index.js. Add a per-socket token bucket created on connection and removed on disconnect, with capacity and refill rate as constants that can be overridden from the environment, checked in the chat message handler before the database insert; do not limit the history replay. In index.html pass a callback that shows a notice when the ack carries an error. Add socket.io-client as a dev dependency and a node --test suite that starts server.js on port 0 with a temporary database, sends a burst past the limit and asserts the last ack carries error rate_limited, that a limited message reaches no other client, and that messages pass again after refill. Run npm install, npm test and node --check index.js, start index.js once to confirm the workers listen, and open a pull request that explains why the limit is per socket and not per address.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

What comes back is a pull request that adds server.js and test/rate-limit.test.js, changes index.js, index.html and package.json, and leaves the database schema alone. The description explains the ack contract in one paragraph: the client retries only unacknowledged packets, so a limit that drops silently amplifies a flood and a limit that acks with an error ends it, and it states that the limit is per socket because each socket is pinned to one cluster worker.

The run's record keeps the npm test output with the burst, the error ack and the post-refill success, and the startup lines from each worker, so a reviewer can see the limit engage and release rather than trust the constants.

Before merging, a reviewer picks the capacity and refill rate for real traffic, decides whether a repeat offender should be disconnected after a number of limited messages, and whether a per-address limit shared across workers is needed, which would bring in a store the project does not have. The agent sets conservative defaults and leaves all three as choices.

Run it on every Linear issue labelled abuse

A team that tracks abuse reports in Linear adds an automation on the Project with a linear trigger filtered to the label abuse and a prompt written for the general case: the trigger adds the issue after the prompt, so the run reads what the report describes, whether a flood from one connection or from one address, and shapes the limit to it. Each labelled issue starts one run and a pull request comes back linked from it.

The automation runs as the member who last changed it and needs that member's Linear connection, made once under Settings → Connections. Its max_runs_per_hour cap keeps a wave of reports from starting a run each in the same minute.

The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.

Why run it on Rush?

The mistake in a Socket.IO rate limit is invisible in a code review: a dropped message looks limited until the client's retry loop sends it three more times. The agent runs a real client against the real server in its own sandbox, counts the acks, and the test stays in the repository so the next change to the handler is checked the same way.

Every command stays with the run, from npm install to the burst test's output, and the pull request can cite them. Doing the same across every realtime service a team runs costs no more attention than one, because each run has its own machine and its own record.

Frequently asked questions

Why acknowledge a limited message instead of ignoring it?

Because index.html sets retries: 3 with a ten-second ackTimeout, and Socket.IO resends an unacknowledged packet until a retry succeeds or the limit is reached. An ack with an error payload stops the retries and lets the page tell the user. Ignoring the message would multiply the traffic the limit exists to stop.

Does the cluster adapter share the buckets?

No, and it does not need to. A socket is served by one worker for its whole life, so a bucket keyed by socket.id in that worker's memory is complete. A limit per IP address across workers would need shared state, which is the case the agent describes and leaves out.

What happens on reconnect?

A new socket gets a fresh bucket, so a client could reconnect to reset it. The agent notes this in the pull request; keying the bucket by handshake.address within a worker narrows it, and a store shared across workers closes it, at the cost of adding one.

Why split index.js into two files?

index.js forks workers at import time, so nothing in it can be tested without starting the whole cluster. Moving the app, the Server and the handlers into server.js behind a function lets the test start one instance on port 0 with its own database file while npm start behaves as before.

More Socket.IO jobs

The same job on other stacks

Keep reading