ns_connchan - Manage connection channels.
The command ns_connchan allows one to detach the current channel from a connection thread and manage the connection outside the initiating connection thread. It allows one to write or read to the channel, to define callbacks and to list open connections and to close the connection. The read and write operations on this channel will use directly the driver infrastructure which was in use during the detach command.
The command allows e.g. to read from and to write to all network drivers (such as plain HTTP channels and from SSL/TLS connections). It can be used to implement e.g. WebSockets or asynchronous deliveries (e.g. h264 streams) including secure connections. Therefore, this command is more general than the approaches based on ns_conn channel using plain Tcl channels.
NaviServer maintains an internal table per server to keep track of the detached connection channels and to offer introspection to the state of the detached channels.
The command ns_connchan detach unplugs the connection channel from the current connection thread and stores it with a fresh handle name in a per-virtual-server private table. The command returns the created handle as result.
After this command was issued in a connection thread, all attempts to access the connection socket directly (e.g. via ns_write) will fail.
Close the named connection channel. The -server can be used for cleanup of stale handles.
Returns 1 if the named connection channel exists, 0 otherwise.
Return a list of the currently detached connection channels for the current or named server.
Every list entry contains
name of the channel
name of the thread
start time of the initiating request,
driver,
the IP address of the client,
sent bytes,
received bytes,
the client data as provided via [ns_conn clientdata],
the cmd name of the callback, or "" when no callback is registered,
the callback condition flags, or "" when no callback is registered.
When NaviServer is running in reverse proxy mode, the client IP address is taken from the value as provided by the reverse proxy server.
Register a Tcl callback for the named connection channel. -timeout is the poll timeout, -receivetimeout is a timeout for incoming packets, -sendtimeout is the timeout for outgoing packets. When -sendtimeout has the value of 0, a read operation might return the empty string. A value larger than 0 might block the event processing for the specified time. All timeouts values are specified in the form secs?:microseconds?, or secs.fraction or as a number with a time unit.
The argument when consist of one or more characters of r, w, e, or x, specifying, when the callback should fire.
When the callback is fired, the specified Tcl command will be called with an additional argument, which is an indicator for the reason of the call when. The value of when will be as follows:
r - the socket is readable
w - the socket is writable
e - the socket has an exceptional condition
x - the server is shutting down
t - timeout received
When the callback exits, its return value determines, whether the callback should be canceled or not. The return value is interpreted as follows:
0 - the callback is canceled, and the channel is deleted automatically (typically, when an error occurs)
1 - the callback will be used as well for further events
2 - the callback will be suspended. No further events will be fired, but the channel is not deleted.
Open a client connection channel to the specified host and port. The command is similar to ns_connchan open, but does less: While ns_connchan open sends an HTTP request to the server denoted by a URL, ns_connchan connect just connects to the server without sending any request data.
The option -tls will connection via TLS, otherwise the connection is via plain socket. -timeout specifies the timeout for establishing the connection (default 1 second). The timeout value t can be specified in the form secs?:microseconds?, or secs.fraction, or as a number with a time unit.
Open listening socket. Call the script callback on incoming connections. On success, this command returns a dict containing "channel", "port", "sock" and "address".
Open a connection channel to the specified url. The URL can either be an HTTP or an HTTPS URL. The driver for the protocol of the url must be loaded: nssock for HTTP, nsssl for HTTPS. A driver can be loaded without configuring a socket for it by setting the port to 0.
The options can be any of:
Read from the specified connection channel and return the received data.
When the option -websocket is used, then the command expects WebSocket frames. In this mode, the result of the command is a Tcl dict containing the following elements:
fin status bit, frame state (incomplete or complete), unprocessed (received number of bytes in buffer not handled so far), fragments (number of bytes in the WebSocket fragments buffer), haveData (boolean value to express that unprocessed data might be sufficient for the next frame without an extra read operation.
In case the frame is finished (fin status bit is set), the dict contains as well the WebSocket opcode and the payload of the frame.
Query status information from the specified connection channel. The command returns a dict containing the following elements:
driver (module name the driver), fragments (for WebSocket read operations: number of bytes in the WebSocket fragments buffer), framebuffer (for WebSocket read operations: number of bytes in the WebSocket frame buffer), peer (communication peer, the IP address of the other side of the channel), received (number of bytes received), sendbuffer (for buffered write operations: number of bytes in the send buffer), sent (number of bytes sent), and start (time when the connection started). When a callback is defined for this channel, the dict contains as well the callback and the condition on which the callback will be fired.
returns a binary websocket frame based on the provided information in the form of a Tcl byte array. When -mask is specified, the data will be masked with random information. For the opcode binary, the input is treated as binary as well. When -binary is used, the data will be treated as binary. This is e.g. necessary on multi-segment messages, where later segments have the opcode continue.
Write to the specified connection channel. The function returns the number of bytes sent, which might be less than the input length.
When the option -buffered is used, then for partial write operations the data which could not be sent is handled internally. The command returns like in non-buffered mode the number of bytes sent, but keeps the reminder and will process this data together with the next write operation (e.g. called with an empty string as last argument). By using the buffered mode, the Tcl programmer does not have to care about sending the non-sent chunk again and to concatenate this with potentially more data from other write operations.