Package se.entra.phantom.server.socket

Native TCP/IP socket communication layer for the NetPhantom server.

See: Description

Interface Summary

Interface	Description
ISocket	Interface to access the socket class.

Class Summary

Class	Description
SocketAdapter	Wraps the socket instance with an ISocket.
SocketClientCommunication	This class communicates with the client over native TCP/IP (Socket).
SocketClientConnectionListener	This instance creates a server socket at a specified port and waits for clients that want a connection to the server.

Package se.entra.phantom.server.socket Description

Native TCP/IP socket communication layer for the NetPhantom server.

This package implements the server-side socket infrastructure that accepts incoming client connections over plain TCP/IP (with optional SSL/TLS), reads and writes framed binary transactions, and dispatches connections to the appropriate handler (NetPhantom client, Remote Application, Remote Assistance relay, or HTTP/WebSocket server).

Class Overview

Package contents

Class	Role
ISocket	Abstraction over Socket and SSLSocket, providing a unified interface for I/O, lifecycle, and SSL handshake operations.
SocketAdapter	Default ISocket implementation that wraps a standard Socket or SSLSocket. For SSL sockets, it provides a BufferedInputStream wrapper to support mark/reset during renegotiation handshakes.
SocketClientCommunication	Per-client communication handler implementing ClientCommunicationInterface. Reads and writes length-prefixed binary transactions (4-byte big-endian size header, with bit 31 indicating deflate compression). Created by the connection listener when a client is accepted.
SocketClientConnectionListener	Server socket listener implementing ClientConnectionInterface. Creates and manages one or more accepter threads, handles SSL handshakes in separate threads, dispatches connections based on the first byte read from the client (protocol identification), and integrates with load balancing and Let's Encrypt certificate management.

Connection Protocol

After a TCP connection is accepted and (optionally) an SSL handshake completes, the server reads a single byte from the client to determine the protocol:

Protocol identification bytes

Byte	Protocol	Action
1	NetPhantom Client	Responds with 1 (accepted), creates SocketClientCommunication, calls onClientConnect.
2	Remote Assistance Relay	Delegates to RemoteAssistanceServer.startRelay().
3	Remote Application (RAPP)	Responds with 1 (accepted), creates SocketClientCommunication, calls onRemoteApplicationConnect.
Other	Web server / unknown	Delegates to onUnknownConnect (typically HTTP or WebSocket).
-1	EOF	Socket closed immediately — no action.

Transaction Framing

NetPhantom client transactions are framed with a 4-byte big-endian header:

• Bit 31 (sign bit): 1 = deflate-compressed payload, 0 = raw.
• Bits 0–30: payload size in bytes (max 16 MB).

SSL Support

SSL/TLS is provided via NetPhantomJSSEServerSocket and is configured per-port through INI file sections. Features include:

• Per-port SSL configuration with independent keystores and settings.
• Let's Encrypt (ACME) certificate management via domain bindings.
• External SSL termination support (e.g. behind a reverse proxy).
• Synchronous SSL renegotiation via SocketAdapter.doSynchronousSSLHandshake(int).

Threading Model

Each port listener runs one or more accepter threads (configurable via accepterThreads in the INI file). When a connection is accepted, the SSL handshake and protocol identification are performed in a dedicated ServerSocketAccepter thread to avoid blocking the accept loop. Accepter threads run at Thread.MAX_PRIORITY - 1; handshake threads run at normal priority (5).

Configuration (INI file)

Port settings are read from [Port] sections in the server INI file. Key parameters include: port, mapToPort, bindAddress, queueLength, sslSection, readTimeout, accepterThreads, loadBalance, externalSSL, and domains (for Let's Encrypt).

(C) Copyright Mindus SARL, 2026. All rights reserved.

Author:

Christopher Mindus

See Also:

ClientConnectionInterface, ClientCommunicationInterface, ServerSocketInterface2, NetPhantomJSSEServerSocket