Skip to content

Docs: updating docs #42

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
F18-Ray wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Docs: updating docs #42

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
75235b9
Docs: updating docs
F18-Ray May 25, 2026
e78e27c
Docs: updating Docs
F18-Ray May 25, 2026
37b9643
Docs: updating TCP_Server_APIs.rst
F18-Ray May 26, 2026
d2f2f1e
Docs: updating TCP_Server_APIs.rst
F18-Ray May 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
167 changes: 100 additions & 67 deletions docs/Network_APIs/TCP_Client_APIs.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,9 @@ The TCP Client APIs
TCP Client setup API
--------------------

The TCP Client Setup API is used to create a TCP client that connects to
``TCP_Server_Base`` and supports message exchange, extension commands,
The TCP Client Setup API is used to create a TCP
client that connects to ``TCP_Server_Base`` and
supports message exchange, extension commands,
interactive console input, and file transfer.

.. code-block:: python
Expand All @@ -22,10 +23,11 @@ interactive console input, and file transfer.
is_input_command_in_console: Any=True,
is_wait_server: Any=True,
max_custom_workers: Any=10,
is_extend_command: Any=False) -> None: ...
is_extend_command: Any=False) -> None:
...

The constructor initializes the client environment and internal state.
The arguments are:
The constructor initializes the client environment
and internal state. The arguments are:

- ``host``: Server host to connect to. If ``None``, the client may be
used for temporary socket modes or manual connect management.
Expand All @@ -42,41 +44,49 @@ The arguments are:
- ``max_custom_workers``: Maximum worker threads for custom commands.
- ``is_extend_command``: If ``True``, the client does not auto-start.

The constructor also prepares the project temp directory under
``.ServSpy/temp_info``, loads the command decode table from
``decode_command_table.json``, initializes the thread pool, and sets up
file-transfer state.
The constructor also prepares the project temp directory
under ``.ServSpy/temp_info``, loads the command decode
table from ``decode_command_table.json``, initializes the
thread pool, and sets up file-transfer state.

.. note::

When ``is_extend_command`` is ``False``, the constructor automatically
calls ``start_TCP_client()`` and begins the client lifecycle.
*Note: When ``is_extend_command`` is ``False``, the
constructor automatically calls ``start_TCP_client()``
and begins the client lifecycle.*

TCP Client connection API
-------------------------

.. code-block:: python

def connect(self: Self) -> bool: ...
def receive_messages(self: Self) -> None: ...
def close(self: Self) -> None: ...
def start_TCP_client(self: Self) -> None: ...

``connect`` creates a TCP socket, binds to ``client_host`` and
``client_port`` if configured, and connects to ``host:port``. On
success, it starts ``receive_messages`` on a background thread.

If ``is_wait_server`` is ``True`` the client will keep waiting for the
server to start when the connection is refused or times out. If
``is_wait_server`` is ``False``, connection failures are reported and
``connect`` returns ``False``.

``receive_messages`` reads UTF-8 data from the server socket into a
newline-delimited buffer. Each complete message line is printed and
commands starting with ``/`` are passed to ``handle_server_command``.

``close`` stops the client, closes the socket, and releases allocated
ports if manual port allocation is enabled.
def connect(self: Self) -> bool:
...
def receive_messages(self: Self) -> None:
...
def close(self: Self) -> None:
...
def start_TCP_client(self: Self) -> None:
...

``connect`` creates a TCP socket, binds to ``client_host``
and ``client_port`` if configured, and connects to
``host:port``. On success, it starts ``receive_messages``
on a background thread.

If ``is_wait_server`` is ``True`` the client will
keep waiting for the server to start when the
connection is refused or times out. If
``is_wait_server`` is ``False``, connection
failures are reported and ``connect`` returns
``False``.

``receive_messages`` reads UTF-8 data from the server
socket into a newline-delimited buffer. Each complete
message line is printed and commands starting with
``/`` are passed to ``handle_server_command``.

``close`` stops the client, closes the socket, and
releases allocated ports if manual port allocation
is enabled.

TCP Client I/O API
------------------
Expand All @@ -85,21 +95,30 @@ The client provides small helpers for socket I/O.

.. code-block:: python

def send_message(self: Self, client_socket: Any, message: Any) -> bool: ...
def recieve_message(self: Self, client_socket: Any, msg_length: int) -> bytes: ...
def send_message(
self: Self,
client_socket: Any,
message: Any) -> bool:
...
def recieve_message(
self: Self,
client_socket: Any,
msg_length: int) -> bytes:
...

``send_message`` accepts ``str`` or ``bytes`` payloads, appends a newline
for text messages, encodes UTF-8, and sends the complete payload with
``send_message`` accepts ``str`` or ``bytes``
payloads, appends a newline for text messages,
encodes UTF-8, and sends the complete payload with
``sendall``.

``recieve_message`` wraps ``socket.recv`` and returns raw bytes from the
socket.
``recieve_message`` wraps ``socket.recv`` and returns
raw bytes from the socket.

TCP Client command API
----------------------

The client supports built-in commands from the server and custom
extensible commands via ``register_command``.
The client supports built-in commands from the server
and custom extensible commands via ``register_command``.

Built-in server-driven commands handled by
``handle_server_command`` include:
Expand All @@ -122,10 +141,12 @@ Built-in server-driven commands handled by
command_name: Any,
handler: Any,
where_to_run: Any,
run_in_thread: bool=False) -> bool: ...
run_in_thread: bool=False) -> bool:
...

This API registers a custom command handler for either server-originated
commands or console-side commands.
This API registers a custom command handler for
either server-originated commands or console-side
commands.

- ``command_name``: command string, typically starting with ``/``.
- ``handler``: callable invoked with ``(client_socket, client_address,
Expand All @@ -145,9 +166,10 @@ error replies back to the server.
Interactive console commands
----------------------------

When ``is_input_command_in_console`` is ``True``, ``interactive_mode``
reads user input and translates console commands into actions.
Supported commands include:
When ``is_input_command_in_console`` is ``True``,
``interactive_mode`` reads user input and translates
console commands into actions. Supported commands
include:

- ``/quit``: send quit to the server and close the client.
- ``/file <path>``: send a file to the server using client-side transfer.
Expand All @@ -156,14 +178,15 @@ Supported commands include:
- ``/multiple_file_folder <folder1> <folder2> ...``: send multiple folders.

If a console command is registered via ``register_command(...,
where_to_run='client')``, it is executed instead of the default send
behavior.
where_to_run='client')``, it is executed instead of
the default send behavior.

TCP Client file transfer API
----------------------------

The client supports both outgoing transfers to the server and incoming
transfers initiated by the server.
The client supports both outgoing transfers to the
server and incoming transfers initiated by the
server.

Client-to-server file transfer flow:

Expand All @@ -182,17 +205,19 @@ Client-to-server file transfer flow:
filename: Any,
server_address: Any,
server_port: Any,
client_port: Any) -> bool: ...
client_port: Any) -> bool:
...

The client waits for the server start-sign message before sending file
metadata. It sends:
The client waits for the server start-sign message before
sending file metadata. It sends:

- 4 bytes: encoded filename length
- filename bytes
- 8 bytes: encoded file size
- file payload in chunks

It then waits for the server confirmation sign before reporting success.
It then waits for the server confirmation sign before
reporting success.

Server-to-client file receive flow:

Expand All @@ -212,30 +237,37 @@ Server-to-client file receive flow:
client_id: Any,
new_save_path: Any,
file_name: Any,
command: Any) -> None: ...
command: Any) -> None:
...

The receive flow writes incoming files to ``received_files`` by default
and supports optional folder-relative save paths or explicit names.
The receive flow writes incoming files to
``received_files`` by default and supports
optional folder-relative save paths or
explicit names.

Port allocation API
-------------------

The client can allocate ports manually when the server requests a client
port range. This is controlled by ``/client_alloc_port_range`` and the
following methods:
The client can allocate ports manually
when the server requests a client port
range. This is controlled by ``/client_alloc_port_range``
and the following methods:

- ``alloc_port`` / ``free_port``: top-level manual port allocation with
lock file coordination.
- ``hand_alloc_port`` / ``hand_free_port``: persistent port allocation
state under ``.ServSpy/temp_info/clients_port_info.log``.

Manual allocation uses ``client_port_lock.lock`` to serialize updates,
so multiple client processes do not conflict when writing port state.
Manual allocation uses ``client_port_lock.lock``
to serialize updates, so multiple client
processes do not conflict when writing port
state.

Temporary server and client helpers
-----------------------------------

The client offers lightweight helpers for temporary connections:
The client offers lightweight helpers for
temporary connections:

.. code-block:: python

Expand All @@ -252,8 +284,9 @@ The client offers lightweight helpers for temporary connections:
bind_port: Any=None,
on_data: Any=None) -> Any: ...

These helpers are useful for file-transfer coordination or short-lived
peer interactions without interfering with the main client socket.
These helpers are useful for file-transfer
coordination or short-lived peer interactions
without interfering with the main client socket.

Helper APIs
-----------
Expand Down Expand Up @@ -289,7 +322,7 @@ Sending a file from the client console:

/file /path/to/file

See also
See Also
--------

For the server-side companion APIs and behavior, refer to
Expand Down
66 changes: 65 additions & 1 deletion docs/Network_APIs/TCP_Server_APIs.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -475,6 +475,9 @@ functions, please visit ...

The file transfer API for you to use includes:

The basic function for the server-to-client
file transfer is defined as:

.. code-block:: python

def file_transfer_server_recv_client_start(
Expand All @@ -483,22 +486,41 @@ The file transfer API for you to use includes:
file_folder_abspath: Any) -> None|False:
...

The file transfer function which will run in
the threads is defined as:

.. code-block:: python

def file_transfer_server_recv_client_start_thread(
self: Self,
message: Any,
file_folder_abspath: Any=None) -> None:
...

The folder transfer function is defined as:

.. code-block:: python

def folder_file_transfer_server_recv_client_start(
self: Self,
message: Any) -> None|False:
...

The multiple files transfer to multiple clients
function is defined as:

.. code-block:: python

def multiple_file_multiple_client_transfer_server_recv_client_start(
self: Self,
message: Any) -> None|False:
...


The different multiple files transfer to the
different multiple clients function is defined as:

.. code-block:: python

def diff_multiple_file_diff_multiple_client_transfer_server_recv_client_start(
self: Self,
message: Any) -> None|False:
Expand Down Expand Up @@ -559,6 +581,41 @@ Common file transfer helper methods include:
Port allocation API
-------------------

The server allocation APIs allow you to alloc a new
port for another servers. There are two kinds of port
allocation modes.

We most recommand you that to use the automaticlly port
allocation mode, which is the default mode of the server,
because the automaticlly port allocation mode is more
simple and also more stable than the manual port
allocation mode. In this mode, when calling the
allocation APIs, it will return ``0``.

*Note: The `bind` function in standard lib `socket`
of the python executor, when input ``0`` to the port
parameter, will automatically assign an available port
by operating system.*

The another port allocation mode is the manual port
allocation mode, there is a port allocation range
for the server. Please avoid to open other servers
in the same host, because in the existing version,
the port allocation range will be conflicted and
some unexpected errors may be caused.

The range of the port allocation is configured in
the server settings. The minimum allocatable port is
``self.port-self.port_add_step*self.port_range_num``,
and the maximum allocatable port is
``self.port+1+self.port_add_step*self.port_range_num``.

*Note: The ``self.port`` is the args ``port`` of the
server class. The ``self.port_add_step`` is the args
``port_add_step`` of the server class. And the
``self.port_range_num`` is the args ``port_range_num``
of the server class also.*

When ``is_hand_alloc_port`` is ``True``, the server
uses manual port allocation and lock files to avoid
conflicts across multiple server instances. The relevant
Expand Down Expand Up @@ -587,3 +644,10 @@ on ``TCP_Server_Base``:
These APIs make it easier to extend the base
TCP server for custom command handling, background
tasks, and temporary connections.

See Also
--------

For more informations about the client APIs,
please visit the client API documentation, at
:doc:`TCP_Client_APIs`.
Loading