Auto-dup fd in reactor_register_fd for safe socket handoff

- reactor_register_fd now calls dup() on the fd automatically
- Sets owns_fd=true so the duplicated fd is closed on cleanup
- Users can safely close Erlang's socket after handoff
- Updated documentation to reflect automatic dup()

Author: benoitc

c_src/py_event_loop.c

@@ -2904,14 +2904,22 @@ ERL_NIF_TERM nif_reactor_register_fd(ErlNifEnv *env, int argc,
         return make_error(env, "invalid_pid");
     }
 
+    /* Duplicate the fd so we own our copy independent of Erlang's socket.
+     * This prevents issues when Erlang's socket is garbage collected. */
+    int dup_fd = dup(fd);
+    if (dup_fd < 0) {
+        return make_error(env, "dup_failed");
+    }
+
     /* Allocate fd resource */
     fd_resource_t *fd_res = enif_alloc_resource(FD_RESOURCE_TYPE,
                                                  sizeof(fd_resource_t));
     if (fd_res == NULL) {
+        close(dup_fd);
         return make_error(env, "alloc_failed");
     }
 
-    fd_res->fd = fd;
+    fd_res->fd = dup_fd;  /* Use duplicated fd */
     fd_res->read_callback_id = 0;  /* Not used for reactor mode */
     fd_res->write_callback_id = 0;
     fd_res->owner_pid = owner_pid;
@@ -2922,7 +2930,7 @@ ERL_NIF_TERM nif_reactor_register_fd(ErlNifEnv *env, int argc,
     /* Initialize lifecycle management */
     atomic_store(&fd_res->closing_state, FD_STATE_OPEN);
     fd_res->monitor_active = false;
-    fd_res->owns_fd = false;  /* Erlang owns the socket via gen_tcp */
+    fd_res->owns_fd = true;  /* We own the duplicated fd */
 
     /* Monitor owner process for cleanup on death */
     if (enif_monitor_process(env, fd_res, &owner_pid,

docs/migration.md

@@ -326,30 +326,40 @@ See [Reactor](reactor.md) for full documentation.
 
 ### Socket FD Handoff
 
-Pass socket file descriptors directly from Erlang to Python for high-performance I/O:
+Pass socket file descriptors directly from Erlang to Python for high-performance I/O.
+
+The reactor automatically `dup()`s the fd, so you can safely close Erlang's socket:
 
 ```erlang
-%% Erlang: Accept connection and get fd
+%% Erlang: Accept and hand off to reactor
 {ok, ClientSock} = gen_tcp:accept(ListenSock),
 {ok, Fd} = inet:getfd(ClientSock),
 
-%% Hand off to Python reactor (Erlang releases ownership)
-py_reactor_context:handoff(Fd, #{type => tcp}).
+%% Hand off fd - reactor dup()s it automatically
+py_reactor_context:handoff(Fd, #{type => tcp}),
+
+%% Safe to close Erlang's socket
+gen_tcp:close(ClientSock).
+```
 
-%% Or pass fd to asyncio-based Python code
+For direct asyncio usage (not via reactor), dup manually:
+
+```erlang
+%% For direct asyncio - dup the fd yourself
+{ok, DupFd} = prim_file:dup(Fd),
 Ctx = py:context(1),
-py:call(Ctx, my_handler, handle_fd, [Fd]).
+py:call(Ctx, my_handler, handle_fd, [DupFd]).
 ```
 
 ```python
-# Python: Use fd with reactor or asyncio
+# Python: Use fd with asyncio
 import socket
-sock = socket.socket(fileno=fd)  # Takes ownership
+sock = socket.socket(fileno=fd)
 sock.setblocking(False)
-# ... use with asyncio or reactor
+# ... use with asyncio
 ```
 
-See [Reactor](reactor.md#passing-sockets-from-erlang-to-python) for details.
+See [Reactor](reactor.md#socket-ownership) for details.
 
 ### `erlang.send()` for Fire-and-Forget Messages
 

docs/reactor.md

@@ -381,26 +381,30 @@ def connect_to(addr: str, port: int):
     # ... use socket
 ```
 
-### Important: Socket Ownership
+### Socket Ownership
 
-When passing an fd from Erlang to Python:
+The reactor automatically duplicates (`dup()`) the file descriptor when you call
+`py_reactor_context:handoff/2`. This means:
 
-1. **Erlang releases ownership**: After `inet:getfd/1`, don't use the Erlang socket
-2. **Python takes ownership**: Close the socket in Python when done
-3. **Don't double-close**: Either Erlang or Python closes, not both
+1. **Erlang keeps its socket** - You can close it whenever convenient
+2. **Python gets its own fd copy** - Independent of Erlang's lifecycle
+3. **No double-close issues** - Each side manages its own fd
 
 ```erlang
-%% WRONG - double close
+%% Simple and safe - reactor handles dup() internally
+{ok, ClientSock} = gen_tcp:accept(ListenSock),
 {ok, Fd} = inet:getfd(ClientSock),
-py_reactor_context:handoff(Fd, #{}),
-gen_tcp:close(ClientSock).  %% BAD: Python will also close
 
-%% RIGHT - let Python handle it
-{ok, Fd} = inet:getfd(ClientSock),
-py_reactor_context:handoff(Fd, #{}).
-%% Don't close ClientSock - Python owns it now
+%% Hand off fd - reactor will dup() it automatically
+py_reactor_context:handoff(Fd, #{type => tcp}),
+
+%% Safe to close Erlang's socket immediately
+gen_tcp:close(ClientSock).
 ```
 
+The reactor will close its duplicated fd when the protocol completes or the
+connection is closed.
+
 ## Integration with Erlang
 
 ### From Erlang: Starting a Reactor Server