@gjsify/net 0.52.0 → 0.53.0

package/lib/esm/server.js

@@ -1 +1 @@
-import"./_virtual/_rolldown/runtime.js";import{Socket as e}from"./socket.js";import t from"@girs/gio-2.0";import{EventEmitter as n}from"node:events";import{createNodeError as r,deferEmit as i,ensureMainLoop as a}from"@gjsify/utils/core";const o=new Set;var Server=class extends n{listening=!1;maxConnections;allowHalfOpen;_service=null;_connections=new Set;_address=null;constructor(e,t){super(),typeof e==`function`?(t=e,this.allowHalfOpen=!1):this.allowHalfOpen=e?.allowHalfOpen??!1,t&&this.on(`connection`,t)}listen(...e){let n=0,s=`0.0.0.0`,c=511,l;if(typeof e[0]==`object`&&e[0]!==null&&!Array.isArray(e[0])){let t=e[0];n=t.port??0,s=t.host??`0.0.0.0`,c=t.backlog??511,l=e[1]}else{typeof e[0]==`number`&&(n=e[0]);for(let t=1;t<e.length;t++)typeof e[t]==`string`?s=e[t]:typeof e[t]==`number`?c=e[t]:typeof e[t]==`function`&&(l=e[t])}l&&this.once(`listening`,l);try{this._service=new t.SocketService,this._service.set_backlog(c);let e;n===0?e=this._service.add_any_inet_port(null):(this._service.add_inet_port(n,null),e=n),this._service.connect(`incoming`,(e,t)=>(this._handleConnection(t),!0)),this._service.start(),a(),this.listening=!0,o.add(this);let r=s.includes(`:`)?`IPv6`:`IPv4`;this._address={port:e,family:r,address:s},i(this,`listening`)}catch(e){let t=r(e,`listen`,{address:s,port:n});i(this,`error`,t)}return this}_handleConnection(t){if(this.maxConnections&&this._connections.size>=this.maxConnections){try{t.close(null)}catch{}return}let n=new e({allowHalfOpen:this.allowHalfOpen});n._setConnection(t),n._setupConnection({}),this._connections.add(n),n.on(`close`,()=>{this._connections.delete(n)}),this.emit(`connection`,n)}address(){return this._address}close(e){if(e&&this.once(`close`,e),!this._service||!this.listening)return setTimeout(()=>{let e=Error(`Server is not running`);e.code=`ERR_SERVER_NOT_RUNNING`,this.emit(`error`,e)},0),this;this._service.stop(),this._service.close(),this._service=null,this.listening=!1,o.delete(this);for(let e of this._connections)e.destroy();return this._connections.clear(),i(this,`close`),this}getConnections(e){e(null,this._connections.size)}ref(){return this}unref(){return this}};export{Server};
+import"./_virtual/_rolldown/runtime.js";import{Socket as e}from"./socket.js";import t from"@girs/gio-2.0";import{closeSocketService as n,releaseListenPort as r}from"@gjsify/utils";import{EventEmitter as i}from"node:events";import{createNodeError as a,deferEmit as o,ensureMainLoop as s,nextTick as c}from"@gjsify/utils/core";const l=new Set;var Server=class extends i{listening=!1;maxConnections;allowHalfOpen;_service=null;_connections=new Set;_closingService=null;_address=null;constructor(e,t){super(),typeof e==`function`?(t=e,this.allowHalfOpen=!1):this.allowHalfOpen=e?.allowHalfOpen??!1,t&&this.on(`connection`,t)}listen(...e){let n=0,i=`0.0.0.0`,c=511,u;if(typeof e[0]==`object`&&e[0]!==null&&!Array.isArray(e[0])){let t=e[0];n=t.port??0,i=t.host??`0.0.0.0`,c=t.backlog??511,u=e[1]}else{typeof e[0]==`number`&&(n=e[0]);for(let t=1;t<e.length;t++)typeof e[t]==`string`?i=e[t]:typeof e[t]==`number`?c=e[t]:typeof e[t]==`function`&&(u=e[t])}u&&this.once(`listening`,u);try{r(n),this._service=new t.SocketService,this._service.set_backlog(c);let e;n===0?e=this._service.add_any_inet_port(null):(this._service.add_inet_port(n,null),e=n),this._service.connect(`incoming`,(e,t)=>(this._handleConnection(t),!0)),this._service.start(),s(),this.listening=!0,l.add(this);let a=i.includes(`:`)?`IPv6`:`IPv4`;this._address={port:e,family:a,address:i},o(this,`listening`)}catch(e){this._service=null;let t=a(e,`listen`,{address:i,port:n});o(this,`error`,t)}return this}_handleConnection(t){if(this.maxConnections&&this._connections.size>=this.maxConnections){try{t.close(null)}catch{}return}let n=new e({allowHalfOpen:this.allowHalfOpen});n._setConnection(t),n._setupConnection({},!1),this._connections.add(n),n.on(`close`,()=>{this._connections.delete(n),this._emitCloseIfDrained()}),this.emit(`connection`,n),n._startReading()}address(){return this._address}close(e){let t=this._service;return e&&this.once(`close`,t?e:()=>{let t=Error(`Server is not running.`);t.code=`ERR_SERVER_NOT_RUNNING`,e(t)}),t&&(this._service=null,this.listening=!1,this._closingService=t,n(t,this._address?[this._address.port]:[],()=>{this._closingService===t&&(this._closingService=null),this._emitCloseIfDrained()})),this._emitCloseIfDrained(),this}_emitCloseIfDrained(){this._service||this._closingService||this._connections.size>0||(l.delete(this),c(()=>this.emit(`close`)))}getConnections(e){e(null,this._connections.size)}ref(){return this}unref(){return this}};export{Server};

package/lib/esm/socket.js

@@ -1 +1 @@
-import"./_virtual/_rolldown/runtime.js";import e from"@girs/gio-2.0";import t from"@girs/glib-2.0";import{Duplex as n}from"node:stream";import{Buffer as r}from"node:buffer";import{createNodeError as i,gbytesToUint8Array as a}from"@gjsify/utils";var Socket=class extends n{remoteAddress;remotePort;remoteFamily;localAddress;localPort;bytesRead=0;bytesWritten=0;connecting=!1;destroyed=!1;pending=!0;readyState=`closed`;_connection=null;_ioStream=null;_inputStream=null;_outputStream=null;_cancellable=new e.Cancellable;_reading=!1;_timeout=0;_timeoutId=null;constructor(e){super(e),this.allowHalfOpen=e?.allowHalfOpen??!1}_setConnection(e){this._connection=e}_setupFromIOStream(t){this._ioStream=t;try{let n=t;if(typeof n.get_socket==`function`){this._connection=n;let t=n.get_remote_address();this.remoteAddress=t.get_address().to_string(),this.remotePort=t.get_port(),this.remoteFamily=t.get_address().get_family()===e.SocketFamily.IPV6?`IPv6`:`IPv4`;let r=n.get_local_address();this.localAddress=r.get_address().to_string(),this.localPort=r.get_port()}}catch{}this._inputStream=t.get_input_stream(),this._outputStream=t.get_output_stream(),this.connecting=!1,this.pending=!1,this.readyState=`open`,this.emit(`connect`),this.emit(`ready`),this._startReading()}_attachOutputOnly(t){this._ioStream=t;try{let n=t;if(typeof n.get_socket==`function`){this._connection=n;let t=n.get_remote_address();this.remoteAddress=t.get_address().to_string(),this.remotePort=t.get_port(),this.remoteFamily=t.get_address().get_family()===e.SocketFamily.IPV6?`IPv6`:`IPv4`;let r=n.get_local_address();this.localAddress=r.get_address().to_string(),this.localPort=r.get_port()}}catch{}this._inputStream=t.get_input_stream(),this._outputStream=t.get_output_stream(),this.connecting=!1,this.pending=!1,this.readyState=`open`,this.emit(`connect`),this.emit(`ready`)}_releaseIOStream(){let e=this._ioStream;return this._ioStream=null,this._inputStream=null,this._outputStream=null,this._connection=null,e}connect(t,n,r){let a;typeof t==`number`?(a={port:t,host:typeof n==`string`?n:`localhost`},typeof n==`function`&&(r=n)):(a=t,typeof n==`function`&&(r=n)),r&&this.once(`connect`,r),this.connecting=!0,this.readyState=`opening`,this.pending=!0;let o=a.host||`localhost`,s=a.port,c=new e.SocketClient;return a.timeout&&c.set_timeout(Math.ceil(a.timeout/1e3)),c.connect_to_host_async(o,s,this._cancellable,(e,t)=>{try{this._connection=c.connect_to_host_finish(t),this._setupConnection(a)}catch(e){this.connecting=!1,this.readyState=`closed`;let t=i(e,`connect`,{address:o,port:s});this.destroy(t)}}),this}_setupConnection(t){if(!this._connection)return;let n=this._connection.get_socket();if(this._inputStream=this._connection.get_input_stream(),this._outputStream=this._connection.get_output_stream(),`keepAlive`in t&&t.keepAlive&&n.set_keepalive(!0),!(`noDelay`in t)||t.noDelay!==!1)try{n.set_option(6,1,1)}catch{}try{let t=this._connection.get_remote_address();this.remoteAddress=t.get_address().to_string(),this.remotePort=t.get_port(),this.remoteFamily=t.get_address().get_family()===e.SocketFamily.IPV6?`IPv6`:`IPv4`}catch{}try{let e=this._connection.get_local_address();this.localAddress=e.get_address().to_string(),this.localPort=e.get_port()}catch{}this.connecting=!1,this.pending=!1,this.readyState=`open`,this.emit(`connect`),this.emit(`ready`),this._startReading()}_startReading(){this._reading||!this._inputStream||(this._reading=!0,this._readLoop())}async _readLoop(){let e=this._inputStream;if(e)try{for(;this._reading&&e;){let n=await new Promise((n,r)=>{e.read_bytes_async(16384,t.PRIORITY_DEFAULT,this._cancellable,(t,i)=>{try{n(e.read_bytes_finish(i))}catch(e){r(e)}})});if(!n||n.get_size()===0){this._reading=!1,this.allowHalfOpen?this.readyState=this.writable?`writeOnly`:`closed`:this.once(`end`,()=>{this.end(),this.readyState=`closed`}),this.push(null);break}let i=a(n);if(this.bytesRead+=i.length,this._resetTimeout(),!this.push(r.from(i))){this._reading=!1;break}}}catch(e){this._cancellable.is_cancelled()||this.destroy(i(e,`read`,{address:this.remoteAddress}))}}_read(e){!this._reading&&this._inputStream&&this._startReading()}_write(e,n,a){if(!this._outputStream){a(Error(`Socket is not connected`));return}let o=r.isBuffer(e)?e:typeof e==`string`?r.from(e,n):r.from(e);this._outputStream.write_bytes_async(new t.Bytes(o),t.PRIORITY_DEFAULT,this._cancellable,(e,t)=>{try{let e=this._outputStream.write_bytes_finish(t);this.bytesWritten+=e,this._resetTimeout(),a(null)}catch(e){a(i(e,`write`,{address:this.remoteAddress}))}})}_final(e){if(this._connection)try{this._connection.get_socket().shutdown(!1,!0),this.readyState=this.readable?`readOnly`:`closed`}catch{}else if(this._ioStream){try{this._ioStream.close(null),this.readyState=`closed`}catch{}this._ioStream=null,this._inputStream=null,this._outputStream=null}e()}_destroy(e,t){if(this._reading=!1,this._clearTimeout(),this._cancellable.cancel(),this._connection){try{this._connection.close(null)}catch{}this._connection=null}else if(this._ioStream)try{this._ioStream.close(null)}catch{}this._ioStream=null,this._inputStream=null,this._outputStream=null,this.readyState=`closed`,this.destroyed=!0,t(e)}setTimeout(e,t){return this._timeout=e,this._clearTimeout(),t&&this.once(`timeout`,t),e>0&&this._resetTimeout(),this}_resetTimeout(){this._clearTimeout(),this._timeout>0&&(this._timeoutId=setTimeout(()=>{this.emit(`timeout`)},this._timeout))}_clearTimeout(){this._timeoutId!==null&&(clearTimeout(this._timeoutId),this._timeoutId=null)}setKeepAlive(e,t){return this._connection?.get_socket().set_keepalive(e??!1),this}setNoDelay(e){if(this._connection)try{this._connection.get_socket().set_option(6,1,e===!1?0:1)}catch{}return this}destroySoon(){this.writable&&this.end(),this.writableFinished?this.destroy():this.once(`finish`,this.destroy.bind(this))}address(){return this.localAddress&&this.localPort?{port:this.localPort,family:this.remoteFamily||`IPv4`,address:this.localAddress}:{}}ref(){return this}unref(){return this}};export{Socket};
+import"./_virtual/_rolldown/runtime.js";import e from"@girs/gio-2.0";import t from"@girs/glib-2.0";import{Duplex as n}from"node:stream";import{Buffer as r}from"node:buffer";import{createNodeError as i,gbytesToUint8Array as a}from"@gjsify/utils";function destroyedError(){let e=Error(`Cannot call write after a stream was destroyed`);return e.code=`ERR_STREAM_DESTROYED`,e}var Socket=class extends n{remoteAddress;remotePort;remoteFamily;localAddress;localPort;bytesRead=0;bytesWritten=0;connecting=!1;destroyed=!1;pending=!0;readyState=`closed`;_connection=null;_ioStream=null;_inputStream=null;_outputStream=null;_cancellable=new e.Cancellable;_readCancellable=new e.Cancellable;_reading=!1;_detaching=!1;_detachResolve=null;_pendingIo=0;_afterIo=null;_timeout=0;_timeoutId=null;constructor(e){super(e),this.allowHalfOpen=e?.allowHalfOpen??!1}_setConnection(e){this._connection=e}_setupFromIOStream(t){this._ioStream=t;try{let n=t;if(typeof n.get_socket==`function`){this._connection=n;let t=n.get_remote_address();this.remoteAddress=t.get_address().to_string(),this.remotePort=t.get_port(),this.remoteFamily=t.get_address().get_family()===e.SocketFamily.IPV6?`IPv6`:`IPv4`;let r=n.get_local_address();this.localAddress=r.get_address().to_string(),this.localPort=r.get_port()}}catch{}this._inputStream=t.get_input_stream(),this._outputStream=t.get_output_stream(),this.connecting=!1,this.pending=!1,this.readyState=`open`,this.emit(`connect`),this.emit(`ready`),this._startReading()}_attachOutputOnly(t){this._ioStream=t;try{let n=t;if(typeof n.get_socket==`function`){this._connection=n;let t=n.get_remote_address();this.remoteAddress=t.get_address().to_string(),this.remotePort=t.get_port(),this.remoteFamily=t.get_address().get_family()===e.SocketFamily.IPV6?`IPv6`:`IPv4`;let r=n.get_local_address();this.localAddress=r.get_address().to_string(),this.localPort=r.get_port()}}catch{}this._inputStream=t.get_input_stream(),this._outputStream=t.get_output_stream(),this.connecting=!1,this.pending=!1,this.readyState=`open`,this.emit(`connect`),this.emit(`ready`)}_releaseIOStream(){let e=this._ioStream;return this._ioStream=null,this._inputStream=null,this._outputStream=null,this._connection=null,e}_claimConnection(){let e={connection:this._connection,ioStream:this._ioStream,inputStream:this._inputStream,outputStream:this._outputStream};return this._connection=null,this._ioStream=null,this._inputStream=null,this._outputStream=null,e}connect(t,n,r){let a;typeof t==`number`?(a={port:t,host:typeof n==`string`?n:`localhost`},typeof n==`function`&&(r=n)):(a=t,typeof n==`function`&&(r=n)),r&&this.once(`connect`,r),this.connecting=!0,this.readyState=`opening`,this.pending=!0;let o=a.host||`localhost`,s=a.port,c=new e.SocketClient;return a.timeout&&c.set_timeout(Math.ceil(a.timeout/1e3)),c.connect_to_host_async(o,s,this._cancellable,(e,t)=>{try{let e=c.connect_to_host_finish(t);if(this.destroyed){e.close(null);return}this._connection=e,this._setupConnection(a)}catch(e){this.connecting=!1,this.readyState=`closed`;let t=i(e,`connect`,{address:o,port:s});this.destroy(t)}}),this}_setupConnection(t,n=!0){if(!this._connection)return;let r=this._connection.get_socket();if(this._inputStream=this._connection.get_input_stream(),this._outputStream=this._connection.get_output_stream(),`keepAlive`in t&&t.keepAlive&&r.set_keepalive(!0),!(`noDelay`in t)||t.noDelay!==!1)try{r.set_option(6,1,1)}catch{}try{let t=this._connection.get_remote_address();this.remoteAddress=t.get_address().to_string(),this.remotePort=t.get_port(),this.remoteFamily=t.get_address().get_family()===e.SocketFamily.IPV6?`IPv6`:`IPv4`}catch{}try{let e=this._connection.get_local_address();this.localAddress=e.get_address().to_string(),this.localPort=e.get_port()}catch{}this.connecting=!1,this.pending=!1,this.readyState=`open`,this.emit(`connect`),this.emit(`ready`),n&&this._startReading()}_startReading(){this._reading||!this._inputStream||(this._reading=!0,this._readLoop())}async _readLoop(){let e=this._inputStream;if(e)try{for(;this._reading&&e;){let n=await new Promise((n,r)=>{this._pendingIo++,e.read_bytes_async(16384,t.PRIORITY_DEFAULT,this._readCancellable,(t,i)=>{try{n(e.read_bytes_finish(i))}catch(e){r(e)}finally{this._ioSettled()}})});if(this._detaching){this._resolveDetach(n&&n.get_size()>0?r.from(a(n)):null);return}if(!n||n.get_size()===0){this._reading=!1,this.allowHalfOpen?this.readyState=this.writable?`writeOnly`:`closed`:this.once(`end`,()=>{this.end(),this.readyState=`closed`}),this.push(null),this.read(0);break}let i=a(n);if(this.bytesRead+=i.length,this._resetTimeout(),!this.push(r.from(i))){this._reading=!1;break}}}catch(e){if(this._detaching){this._resolveDetach(null);return}this._readCancellable.is_cancelled()||this.destroy(i(e,`read`,{address:this.remoteAddress}))}}_detachReader(){return this._reading?(this._detaching=!0,this._reading=!1,this._readCancellable.cancel(),new Promise(e=>{this._detachResolve=e})):Promise.resolve(null)}_resolveDetach(e){this._detaching=!1;let t=this._detachResolve;this._detachResolve=null,t&&t(e)}_read(e){!this._reading&&this._inputStream&&this._startReading()}_write(e,n,a){if(!this._outputStream){a(Error(`Socket is not connected`));return}let o=r.isBuffer(e)?e:typeof e==`string`?r.from(e,n):r.from(e),s=this._outputStream;this._pendingIo++,s.write_bytes_async(new t.Bytes(o),t.PRIORITY_DEFAULT,this._cancellable,(e,t)=>{let n=null;try{let e=s.write_bytes_finish(t);this.bytesWritten+=e,this._resetTimeout()}catch(e){n=this._cancellable.is_cancelled()?destroyedError():i(e,`write`,{address:this.remoteAddress})}this._ioSettled(),a(n)})}_final(e){if(this._connection)try{this._connection.get_socket().shutdown(!1,!0),this.readyState=this.readable?`readOnly`:`closed`}catch{}else if(this._ioStream){try{this._ioStream.close(null),this.readyState=`closed`}catch{}this._ioStream=null,this._inputStream=null,this._outputStream=null}e()}_destroy(e,t){this._reading=!1,this._clearTimeout(),this._cancellable.cancel(),this._readCancellable.cancel();let release=()=>this._release(e,t);this._pendingIo===0?release():this._afterIo=release}_ioSettled(){if(this._pendingIo--,this._pendingIo===0&&this._afterIo){let e=this._afterIo;this._afterIo=null,e()}}_release(e,t){if(this._connection){try{this._connection.close(null)}catch{}this._connection=null}else if(this._ioStream)try{this._ioStream.close(null)}catch{}this._ioStream=null,this._inputStream=null,this._outputStream=null,this.readyState=`closed`,this.destroyed=!0,t(e)}setTimeout(e,t){return this._timeout=e,this._clearTimeout(),t&&this.once(`timeout`,t),e>0&&this._resetTimeout(),this}_resetTimeout(){this._clearTimeout(),this._timeout>0&&(this._timeoutId=setTimeout(()=>{this.emit(`timeout`)},this._timeout))}_clearTimeout(){this._timeoutId!==null&&(clearTimeout(this._timeoutId),this._timeoutId=null)}setKeepAlive(e,t){return this._connection?.get_socket().set_keepalive(e??!1),this}setNoDelay(e){if(this._connection)try{this._connection.get_socket().set_option(6,1,e===!1?0:1)}catch{}return this}destroySoon(){this.writable&&this.end(),this.writableFinished?this.destroy():this.once(`finish`,this.destroy.bind(this))}address(){return this.localAddress&&this.localPort?{port:this.localPort,family:this.remoteFamily||`IPv4`,address:this.localAddress}:{}}ref(){return this}unref(){return this}};export{Socket};

package/lib/types/server.d.ts

@@ -12,6 +12,8 @@ export declare class Server extends EventEmitter {
     allowHalfOpen: boolean;
     private _service;
     private _connections;
+    /** A listener `close()` stopped whose descriptors are not closed yet. */
+    private _closingService;
     private _address;
     constructor(connectionListener?: (socket: Socket) => void);
     constructor(options?: {
@@ -31,8 +33,15 @@ export declare class Server extends EventEmitter {
         family: string;
         address: string;
     } | null;
-    /** Close the server, stop accepting new connections. */
+    /**
+     * Stop accepting. Node's contract (net.js `Server.prototype.close`):
+     * connections already accepted stay open, 'close' follows once the listener
+     * AND the last of them are closed, and on a server that is not listening the
+     * callback gets ERR_SERVER_NOT_RUNNING — no 'error' event.
+     */
     close(callback?: (err?: Error) => void): this;
+    /** Node's `_emitCloseIfDrained`: nothing listening, closing, or connected. */
+    private _emitCloseIfDrained;
     /** Get the number of concurrent connections. */
     getConnections(callback: (err: Error | null, count: number) => void): void;
     ref(): this;

package/lib/types/socket.d.ts

@@ -1,5 +1,6 @@
 import Gio from '@girs/gio-2.0';
 import { Duplex } from 'node:stream';
+import { Buffer } from 'node:buffer';
 import type { DuplexOptions } from 'node:stream';
 export interface SocketConnectOptions {
     port: number;
@@ -33,7 +34,36 @@ export declare class Socket extends Duplex {
     private _inputStream;
     private _outputStream;
     private _cancellable;
+    /**
+     * Cancellable dedicated to the read loop's `read_bytes_async` calls,
+     * separate from `_cancellable` (which also guards writes). `_destroy`
+     * cancels both; `_detachReader` cancels only this one, so handing this
+     * socket's connection off to a new owner (a TLS upgrade) never aborts
+     * an unrelated in-flight write.
+     */
+    private _readCancellable;
     private _reading;
+    /**
+     * Set by `_detachReader()` while waiting for the current read to settle.
+     * The read loop checks this instead of pushing to the Duplex, so a read
+     * that resolves with real data (won the race against cancellation) goes
+     * to the detacher instead of being delivered on a socket about to be
+     * abandoned.
+     */
+    private _detaching;
+    private _detachResolve;
+    /**
+     * Gio operations started on this socket's streams whose callback has not run.
+     * Each one keeps a GSource polling the descriptor; `_destroy` cancels them, but
+     * a cancelled operation is only dispatched on the NEXT main-loop iteration, so
+     * closing the descriptor before then leaves a source polling a closed fd. On
+     * Linux poll(2) flags that entry POLLNVAL and moves on; GLib on darwin polls
+     * via select(2), which fails the WHOLE call with EBADF ("poll(2) failed due
+     * to: Bad file descriptor") and starves every other source for that
+     * iteration. So the close waits for the count to reach zero.
+     */
+    private _pendingIo;
+    private _afterIo;
     private _timeout;
     private _timeoutId;
     constructor(options?: SocketOptions);
@@ -56,18 +86,75 @@ export declare class Socket extends Duplex {
      *  Nullifies the socket's stream references so they are not closed when the
      *  socket itself is later destroyed. */
     _releaseIOStream(): Gio.IOStream | null;
+    /**
+     * @internal Atomically hand off this socket's Gio connection/streams to
+     * a new owner (a protocol upgrade: TLS, …), nulling them out here.
+     * Unlike `_releaseIOStream` (which only ever sees a stolen IOStream,
+     * never mid-read — see its one call site), this is also safe to call
+     * on a socket whose read loop is already running: nulling
+     * `_inputStream` makes both `_startReading()`'s own guard and a
+     * `Server._handleConnection`-deferred auto-start no-op, but an
+     * ALREADY in-flight `read_bytes_async` keeps its own local stream
+     * reference regardless — pair this with `_detachReader()` (either
+     * order) when a read may already be pending.
+     */
+    _claimConnection(): {
+        connection: Gio.SocketConnection | null;
+        ioStream: Gio.IOStream | null;
+        inputStream: Gio.InputStream | null;
+        outputStream: Gio.OutputStream | null;
+    };
     /**
      * Initiate a TCP connection.
      */
     connect(options: SocketConnectOptions | number, host?: string | (() => void), connectionListener?: () => void): this;
-    /** @internal Set up streams and emit connect after connection is established. */
-    _setupConnection(opts: SocketConnectOptions | Record<string, never>): void;
-    private _startReading;
+    /**
+     * @internal Set up streams and emit connect after connection is
+     * established. `autoStartReading` (default true) controls the
+     * trailing `_startReading()` call — `Server._handleConnection` passes
+     * `false` so a synchronous 'connection' listener (e.g.
+     * `TLSServer._upgradeTls`) gets a chance to claim the streams first
+     * via `_claimConnection()`, then calls `_startReading()` itself once
+     * every listener has run. `Socket.connect()`'s own 'connect' emit
+     * already runs BEFORE this method's trailing auto-start either way —
+     * a claiming listener there needs no such flag, just to call
+     * `_claimConnection()` synchronously within its own handler.
+     */
+    _setupConnection(opts: SocketConnectOptions | Record<string, never>, autoStartReading?: boolean): void;
+    /**
+     * @internal Not TS-`private`: `Server._handleConnection` (same
+     * package, different class) calls this directly when it deferred
+     * `_setupConnection`'s own auto-start — see that method's doc.
+     */
+    _startReading(): void;
     private _readLoop;
+    /**
+     * @internal Stop the read loop and cancel any in-flight read, then wait
+     * for it to settle — without touching the underlying connection or
+     * streams. Used before handing this socket's Gio connection to a new
+     * owner (a TLS upgrade / STARTTLS): the new owner's
+     * `Gio.TlsClientConnection` issues its own reads on the same
+     * `Gio.InputStream`, and GIO rejects a second concurrent read on one
+     * stream — so any read this socket started must be fully settled first.
+     *
+     * Resolves `null` in the well-behaved case (nothing was pending, or the
+     * pending read was cleanly cancelled before any data arrived — true for
+     * any protocol where the peer waits for our next message, which is what
+     * makes STARTTLS work at all). Resolves the leftover `Buffer` when a
+     * read raced ahead and already had data by the time it noticed the
+     * detach; the caller cannot safely feed that back into a
+     * `Gio.TlsClientConnection` (unlike Node's OpenSSL binding, Gio's TLS
+     * connection owns and reads its base stream directly — there's no
+     * "inject already-read bytes" API), so it must treat this as an error.
+     */
+    _detachReader(): Promise<Buffer | null>;
+    private _resolveDetach;
     _read(_size: number): void;
     _write(chunk: unknown, encoding: string, callback: (error?: Error | null) => void): void;
     _final(callback: (error?: Error | null) => void): void;
     _destroy(err: Error | null, callback: (error?: Error | null) => void): void;
+    private _ioSettled;
+    private _release;
     /** Set the socket timeout in milliseconds. 0 disables. */
     setTimeout(timeout: number, callback?: () => void): this;
     private _resetTimeout;

package/lib/types/teardown.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/net",
-    "version": "0.52.0",
+    "version": "0.53.0",
     "description": "Node.js net module for Gjs",
     "type": "module",
     "module": "lib/esm/index.js",
@@ -41,18 +41,18 @@
         "net"
     ],
     "devDependencies": {
-        "@gjsify/cli": "^0.52.0",
-        "@gjsify/unit": "^0.52.0",
+        "@gjsify/cli": "^0.53.0",
+        "@gjsify/unit": "^0.53.0",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },
     "dependencies": {
         "@girs/gio-2.0": "5.4.0",
         "@girs/glib-2.0": "5.4.0",
-        "@gjsify/buffer": "^0.52.0",
-        "@gjsify/events": "^0.52.0",
-        "@gjsify/stream": "^0.52.0",
-        "@gjsify/utils": "^0.52.0"
+        "@gjsify/buffer": "^0.53.0",
+        "@gjsify/events": "^0.53.0",
+        "@gjsify/stream": "^0.53.0",
+        "@gjsify/utils": "^0.53.0"
     },
     "gjsify": {
         "runtimes": {