ready-bell — UDP ready notifications

Poll less. Know when to check.

How often should you poll for an asynchronous result?

Poll too often → waste requests.
Poll less often → increase latency.

Send a UDP packet to ready-bell.com:3137:

Listen <uuid> 60

When the operation finishes, Ready Bell sends:

Ready <uuid>

Fetch the result immediately.

Low request rate. Low latency.

Finish the work. Send one notification.

Your API starts an asynchronous operation.

When it's done, send a UDP packet to ready-bell.com:3137:

Notify <uuid>

Ready Bell finds the clients listening for that operation and sends them:

Ready <uuid>

Your backend doesn't need to know who's waiting.

One small UDP packet. Ready Bell handles the rest.

How it works

A Listener sends Listen <uuid> <seconds>. Later, a Notifier sends Notify <uuid> when that UUID's result is ready. Ready Bell sends a single Ready <uuid> packet to every Listener currently waiting on it.

Try it in 10 seconds

uuid

Terminal 1 disconnected

Terminal 2 disconnected

Click Listen in one terminal and Notify in the other.

Or try it in your own terminal

Run netcat in two terminals:

terminal 1 and 2

nc -u ready-bell.com 3137

Paste into terminal 1:

Paste into terminal 2:

Protocol reference

ready-bell speaks UTF-8 plain-text messages over UDP. Each datagram carries exactly one command or response.

Initiator	Message	Response	Meaning
Listener client → Server	`Listen <uuid> <ttlSeconds>`	`Registered <uuid> <ip> <port> <ttlSeconds>`	Subscribe to a UUID for up to `ttlSeconds` seconds. The subscription is removed when the TTL expires. `<ip>` and `<port>` are the UDP source address observed by the server.
Notifier client → Server	`Notify <uuid>`	`Notified <uuid> <n>`	Notify all currently subscribed Listener clients. `<n>` is the number of notification packets sent.
Server → Listener client	`Ready <uuid>`	—	Notification sent to every Listener subscribed to the UUID, once per `Notify`.
Any client → Server	Invalid command	`Error: <reason>`	The command could not be parsed or validated.

Multiple Listener clients can subscribe to the same UUID — a Notify sends Ready to all of them. Ready Bell runs over UDP and provides no delivery guarantees: commands, responses, and notifications may be lost, duplicated, or reordered. A Notified response only confirms the server attempted to send the notification, not that it arrived — keep your regular re-check schedule running as the fallback, and treat Ready purely as a hint to check sooner.

Code examples

Every example below talks to the live service at ready-bell.com:3137 — nothing to run or host yourself.

Open two terminals and run this in each:

terminal 1 and 2

nc -u ready-bell.com 3137

In the first terminal, type this line and press enter:

terminal 1

Listen 3fa85f64-5717-4562-b3fc-2c963f66afa6 30

It prints Registered .... Within 30 seconds, type this in the second terminal:

terminal 2

Notify 3fa85f64-5717-4562-b3fc-2c963f66afa6

Terminal 2 prints Notified ... 1, and terminal 1 prints Ready 3fa85f64-5717-4562-b3fc-2c963f66afa6.

Run node listener.js in one terminal
Run node notifier.js in second terminal

listener.js View raw

import dgram from "dgram";

const socket = dgram.createSocket("udp4");
const uuid = "3fa85f64-5717-4562-b3fc-2c963f66afa6";

socket.on("message", msg => console.log(msg.toString().trim()));
socket.send(`Listen ${uuid} 30`, 3137, "ready-bell.com");

notifier.js View raw

import dgram from "dgram";

const socket = dgram.createSocket("udp4");
const uuid = "3fa85f64-5717-4562-b3fc-2c963f66afa6";

socket.once("message", msg => (console.log(msg.toString().trim()), socket.close()));
socket.send(`Notify ${uuid}`, 3137, "ready-bell.com");

Run python listener.py in one terminal
Run python notifier.py in second terminal

listener.py View raw

import socket

uuid = "3fa85f64-5717-4562-b3fc-2c963f66afa6"
addr = ("ready-bell.com", 3137)

with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as s:
    s.sendto(f"Listen {uuid} 30".encode(), addr)
    while True:
        data, _ = s.recvfrom(512)
        print(data.decode().strip())

notifier.py View raw

import socket

uuid = "3fa85f64-5717-4562-b3fc-2c963f66afa6"
addr = ("ready-bell.com", 3137)

with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as s:
    s.sendto(f"Notify {uuid}".encode(), addr)
    data, _ = s.recvfrom(512)
    print(data.decode().strip())

Run java listener.java in one terminal
Run java notifier.java in second terminal

listener.java View raw

import java.net.*;

void main() throws Exception {
    var uuid = "3fa85f64-5717-4562-b3fc-2c963f66afa6";
    var address = new InetSocketAddress("ready-bell.com", 3137);

    try (var socket = new DatagramSocket()) {
        var request = ("Listen " + uuid + " 30").getBytes();
        socket.send(new DatagramPacket(request, request.length, address));

        var packet = new DatagramPacket(new byte[512], 512);
        while (true) {
            socket.receive(packet);
            System.out.println(new String(packet.getData(), 0, packet.getLength()).trim());
        }
    }
}

notifier.java View raw

import java.net.*;

void main() throws Exception {
    var uuid = "3fa85f64-5717-4562-b3fc-2c963f66afa6";
    var address = new InetSocketAddress("ready-bell.com", 3137);

    try (var socket = new DatagramSocket()) {
        var bytes = ("Notify " + uuid).getBytes();
        socket.send(new DatagramPacket(bytes, bytes.length, address));

        var packet = new DatagramPacket(new byte[512], 512);
        socket.receive(packet);

        System.out.println(new String(packet.getData(), 0, packet.getLength()));
    }
}

Drop-in integration for a Quarkus service, taken from the ready-bell-demo project. Incoming Ready notifications are fired as CDI events — handle them with @Observes ReadyBellEvent.

ReadyBellService.java View raw

package readybell;

import java.io.IOException;
import java.net.DatagramPacket;
import java.net.DatagramSocket;
import java.net.InetSocketAddress;
import java.net.SocketException;
import java.nio.charset.StandardCharsets;
import java.util.UUID;
import java.util.concurrent.Executor;

import io.quarkus.logging.Log;
import jakarta.annotation.PostConstruct;
import jakarta.annotation.PreDestroy;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.enterprise.event.Event;
import jakarta.inject.Inject;

@ApplicationScoped
public class ReadyBellService {

    private static final String REMOTE_HOST = "ready-bell.com";
    private static final int REMOTE_PORT = 3137;

    @Inject
    Executor executor;

    @Inject
    Event<ReadyBellEvent> readyEvent;

    private DatagramSocket socket;

    @PostConstruct
    public void init() throws Exception {
        socket = new DatagramSocket();
        executor.execute(this::listenLoop);
        Log.infof("ReadyBellService bound to port: %s", socket.getLocalPort());
    }

    @PreDestroy
    public void destroy() {
        if (socket != null && !socket.isClosed()) {
            socket.close();
            Log.info("ReadyBellService UDP socket closed.");
        }
    }

    public boolean sendListen(UUID uuid, int seconds) {
        return send("Listen " + uuid + " " + seconds);
    }

    public boolean sendNotify(UUID uuid) {
        return send("Notify " + uuid);
    }

    private boolean send(String message) {
        InetSocketAddress target = new InetSocketAddress(REMOTE_HOST, REMOTE_PORT);
        if (target.isUnresolved()) {
            Log.debugf("Failed to resolve %s, dropping message: %s", REMOTE_HOST, message);
            return false;
        }

        try {
            var bytes = message.getBytes(StandardCharsets.UTF_8);
            socket.send(new DatagramPacket(bytes, bytes.length, target));
            Log.debugf("Sent UDP packet: %s", message);
            return true;
        } catch (IOException e) {
            Log.warnf(e, "Failed to send UDP packet: %s", message);
            return false;
        }
    }

    private void listenLoop() {
        var buffer = new byte[512];
        var packet = new DatagramPacket(buffer, buffer.length);

        while (!socket.isClosed() && !Thread.currentThread().isInterrupted()) {
            try {
                socket.receive(packet);
                var message = new String(packet.getData(), 0, packet.getLength(), StandardCharsets.UTF_8).trim();
                Log.debugf("Received UDP packet: %s", message);

                if (message.startsWith("Ready ")) {
                    UUID uuid = UUID.fromString(message.substring("Ready ".length()).trim());
                    readyEvent.fire(new ReadyBellEvent(uuid));
                }
            } catch (SocketException e) {
                Log.infof("UDP socket closed, stopping listener.");
                break;
            } catch (Exception e) {
                Log.errorf(e, "UDP reader error: %s", e.getMessage());
            }
        }
    }
}

ReadyBellEvent.java View raw

package readybell;

import java.util.UUID;

public record ReadyBellEvent(UUID uuid) {
}

Questions, feedback or interested in using Ready Bell?

ready-bell@proton.me

Live demo GitHub

Get results the moment they’re ready.