Reproducing and fixing JupyUvi.stop() port races

You’re close, but there are a couple of important corrections.

A machine does not have one single global port namespace in the simple sense. More precisely, listening sockets are distinguished by a tuple roughly like:

protocol, local IP address, local port

For TCP IPv4, that means these are different listening addresses:

127.0.0.1:8000
192.168.1.131:8000
0.0.0.0:8000

But 0.0.0.0 is special: it means “all IPv4 interfaces”. So binding to:

0.0.0.0:8000

claims port 8000 on every IPv4 interface.

That means if you already have:

192.168.1.131:8000

listening, then trying to bind:

0.0.0.0:8000

will usually fail, because 0.0.0.0:8000 includes 192.168.1.131:8000.

But binding these two may be allowed simultaneously:

127.0.0.1:8000
192.168.1.131:8000

because they are different local IP addresses.

So this part:

you cannot bind the same port for listening to localhost connections

Not quite. You can often bind the same port number on localhost and on a non-loopback interface at the same time:

127.0.0.1:8000
192.168.1.131:8000

But you generally cannot also bind:

0.0.0.0:8000

because that overlaps with both.

The key distinction is:

127.0.0.1      = loopback only
192.168.x.x    = one specific network interface/address
0.0.0.0        = all IPv4 addresses/interfaces

So your notebook’s issue is exactly this asymmetry:

JupyUvi binds server to 0.0.0.0:port
wait_port_free checks localhost:port

The check can say “localhost is free” even though 0.0.0.0:port is not free, because some non-loopback interface is still occupying that port.

One more correction:

expose the local port on an interface that listens for outbound connections

Interfaces do not really “listen for outbound connections.” Listening is about incoming connections to a local IP/port. Outbound connections use a local source IP/port too, but that’s a separate case involving ephemeral ports.

The mental model I’d use is:

A listening TCP socket reserves a port on a specific local address.
0.0.0.0 reserves that port on all local IPv4 addresses.
Therefore, checking localhost alone does not prove that 0.0.0.0 is available.

So yes: the core bug diagnosis is right, but the precise reason is not “one port range across all interfaces”; it is “socket binding is per local address + port, and 0.0.0.0 overlaps with every IPv4 interface.”

Yes — in this case you want the probe to use 0.0.0.0 because that is what Uvicorn is actually trying to bind.

If JupyUvi starts Uvicorn with:

host="0.0.0.0"

then the availability check should test the same thing:

bind(("0.0.0.0", port))

Otherwise you can get a false positive: localhost:port may be free, while 0.0.0.0:port is not.

Why use 0.0.0.0 for Uvicorn at all? Usually because in notebook/container/dev-server contexts you want the app reachable from outside the Python process, for example from:

• the browser environment,
• another container/service,
• the host machine,
• a forwarded/proxied URL.

If Uvicorn binds only to:

127.0.0.1

then it only accepts connections from the same network namespace/machine. In many notebook or container setups, that is too restrictive.

So the rule is:

The port probe should use the same host/interface as the real server.

If JupyUvi(host="127.0.0.1"), check 127.0.0.1.

If JupyUvi(host="0.0.0.0"), check 0.0.0.0.

Binding only to localhost / 127.0.0.1 is okay when the client that needs to connect is in the same network namespace as the server.

It is not okay when the thing trying to open the FastHTML app is “outside” that namespace.

Common cases where JupyUvi(host="127.0.0.1") may fail:

• Containers: inside Docker, 127.0.0.1 means “inside the container”, not the host machine. Your browser on the host cannot reach it unless there is some special proxying.
• Remote notebooks: the Python kernel is running on a remote machine, but your browser is local. 127.0.0.1 on the remote machine is not your laptop’s localhost.
• Cloud notebook/server environments: platforms often expose apps by forwarding traffic to a container/interface. They usually need the app to listen on 0.0.0.0.
• Other devices or services need access: e.g. testing from your phone, another machine on the LAN, a webhook callback, or another container.
• Reverse proxies / port forwarders: a proxy may connect via the container/network interface rather than loopback.

The key idea:

127.0.0.1 = only clients from the same network namespace
0.0.0.0   = clients arriving through any IPv4 interface

In local plain Python on your laptop, localhost is often enough. In notebooks, containers, and hosted environments, 0.0.0.0 is often the safer default because the browser/proxy may not be “inside” the same localhost.

port_free_loose is answer the question:

“Can the kernel create some socket object with this address?”

but what we want to know is:

“Can uvicorn successfully start a normal listening server on this host/port right now?”

• SO_REUSEADDR makes the probe answer a slightly different, more permissive question.
• in the loose version we don't try to listen to the port, only bind.

In this code:

sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
sock.bind((host, port))

you are telling the OS: “please allow some forms of address reuse.” That can make bind() succeed in edge cases where a normal server startup may still fail or behave differently.

For a port-availability probe, that is risky because it can produce a false free result:

probe says:  port is free
uvicorn says: address already in use

So the stricter probe should avoid SO_REUSEADDR and mimic the thing we care about:

sock.bind((host, port))
sock.listen(1)

The probe should be conservative: it is better to wait a bit longer than to tell JupyUvi.stop() that shutdown finished while the old server is still holding the port.

bind and listen are two different stages of making a TCP server socket.

bind((host, port)) says:

“Reserve this local address/port for this socket.”

For example:

s.bind(("0.0.0.0", 8000))

means “attach this socket to port 8000 on all IPv4 interfaces.”

But after bind, the socket is not yet accepting incoming TCP connections. It has only claimed the address.

listen() says:

“Turn this bound socket into a passive server socket that can receive incoming connection attempts.”

So the usual TCP server sequence is:

s.bind((host, port))
s.listen()

Then later the server calls accept() to actually take incoming connections from the queue.

A rough analogy:

bind   = reserve a shop address
listen = open the shop for customers to queue outside
accept = invite the next customer inside

For your port-checking issue, bind alone asks:

“Can I reserve this address?”

But Uvicorn needs:

“Can I reserve this address and open it as a server?”

So a stricter port probe should do both bind and listen.

I think that’s a fair read: Issue 1 and Issue 2 are probably the real culprits for your observed restart race.

The listen() change is still defensible, but it’s more of a correctness/conservatism improvement than likely the main fix.

The important bugs are:

1. stop() checked the wrong host:

wait_port_free(self.port)

instead of:

wait_port_free(self.port, self.host)

That can definitely say “free” when 0.0.0.0:port is not free.

2. wait_port_free() only printed timeout and returned anyway.

So even if the port was still occupied after the wait, stop() continued as if shutdown succeeded.

By comparison, bind() vs bind()+listen() is probably less central. Since Uvicorn itself will create a listening server, using listen() in the probe makes the check closer to reality. But if you had to prioritize, I’d say:

must fix: pass host
must fix: raise/return failure on timeout
nice fix: stricter probe with listen()
maybe fix: avoid SO_REUSEADDR in probe

So yes: your intuition is right. listen() is probably not the key culprit; it’s a “make the probe ask the exact question we care about” improvement.

Issue 1 and issue 3 are different failure modes in the port check:

1. Wrong host

This is about where you check.

JupyUvi starts uvicorn on:

host="0.0.0.0"

but wait_port_free() was effectively checking:

host="localhost"

So it could say “the port is free on localhost” even though the port is not free for 0.0.0.0, which is what the next uvicorn start needs.

So issue 1 is: checking the wrong interface.

3. Too-permissive port check

This is about how you check.

The old check did something like:

s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
s.bind((host, port))

That can say “bind succeeded” in cases where a real server startup may still fail or race, especially around shutdown/restart timing. Your stricter version does:

s.bind((host, port))
s.listen(1)

without SO_REUSEADDR, which better represents “could uvicorn actually listen here now?”

So issue 3 is: checking the right interface too optimistically.

Short version:

Yes. For issue 3, the shortest repro is probably: create a socket using SO_REUSEADDR, bind/listen on it, then show that a second socket using the same option can bind() but cannot listen().

s = socket.socket()
s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
s.bind(("0.0.0.0", 0)); s.listen()
port = s.getsockname()[1]

Then compare old-style probe vs stricter probe:

port_free_loose(port), port_free_strict(port)

Expected result should be roughly:

(True, False)

That demonstrates the problem very directly: bind() with SO_REUSEADDR can say “yes”, but bind() + listen() says “no, a real server cannot listen here.”