socket_protocol (Socket Protocol)¶

Author:

Dirk Alders <sudo-dirk@mount-mockery.de>

Description:

This Module supports point to point communication for client-server issues.

Submodules:

socket_protocol.data_storage
socket_protocol.pure_json_protocol
socket_protocol.struct_json_protocol

Unittest:

See also the unittest documentation.

Module Documentation:

socket_protocol.AUTH_STATE_KEY_TRANSFERRED = 3¶: Authentification Status for ‘Key has been sent’

socket_protocol.AUTH_STATE_SEED_REQUESTED = 1¶: Authentification Status for ‘Seed was requested’

socket_protocol.AUTH_STATE_SEED_TRANSFERRED = 2¶: Authentification Status for ‘Seed has been sent’

socket_protocol.AUTH_STATE_TRUSTED_CONNECTION = 4¶: Authentification Status for a ‘Trusted Connection’

socket_protocol.AUTH_STATE_UNTRUSTED_CONNECTION = 0¶: Authentification Status for an ‘Untrusted Connection’

socket_protocol.AUTH_STATE__NAMES = {0: 'Untrusted Connection', 1: 'Seed was requested', 2: 'Seed has been sent', 3: 'Key has been sent', 4: 'Trusted Connection'}¶: Authentification Status names for previous defined authentification states

socket_protocol.DID_AUTH_KEY = 1¶: DID for authentification (key)

socket_protocol.DID_AUTH_SEED = 0¶: DID for authentification (seed)

socket_protocol.DID_CHANNEL_NAME = 0¶: DID for channel name

exception socket_protocol.RequestSidExistsError¶

exception socket_protocol.ResponseSidExistsError¶

socket_protocol.SID_AUTH_REQUEST = 0¶: SID for authentification request

socket_protocol.SID_AUTH_RESPONSE = 1¶: SID for authentification response

socket_protocol.SID_CHANNEL_NAME_REQUEST = 8¶: SID for channel name exchange request

socket_protocol.SID_CHANNEL_NAME_RESPONSE = 9¶: SID for channel name exchange response

socket_protocol.SID_EXECUTE_REQUEST = 30¶: SID for a execute request

socket_protocol.SID_EXECUTE_RESPONSE = 31¶: SID for a execute response

socket_protocol.SID_READ_REQUEST = 10¶: SID for a read data request

socket_protocol.SID_READ_RESPONSE = 11¶: SID for read data response

socket_protocol.SID_WRITE_REQUEST = 20¶: SID for a write data request

socket_protocol.SID_WRITE_RESPONSE = 21¶: SID for a write data response

socket_protocol.STATUS_AUTH_REQUIRED = 3¶: Status for ‘authentification is required’

socket_protocol.STATUS_BUFFERING_UNHANDLED_REQUEST = 1¶: Status for ‘unhandled request’

socket_protocol.STATUS_CALLBACK_ERROR = 2¶: Status for ‘callback errors’

socket_protocol.STATUS_CHECKSUM_ERROR = 5¶: Status for ‘checksum error’

socket_protocol.STATUS_LOG_LVL = {0: 20, 1: 30, 2: 40, 3: 30, 4: 40, 5: 40, 6: 30}¶: Status depending log level for messages

socket_protocol.STATUS_OKAY = 0¶: Status for ‘okay’

socket_protocol.STATUS_OPERATION_NOT_PERMITTED = 6¶: Status for ‘operation not permitted’

socket_protocol.STATUS_SERVICE_OR_DATA_UNKNOWN = 4¶: Status for ‘service or data unknown’

class socket_protocol.data_storage(*args, **kwargs)¶

This is a storage object for socket_protocol messages.

Parameters:

status (int) – The message status.
service_id (int) – The Service-ID.
data_id (int) – The Data-ID.
data (any) – The transfered data.

get_data(default=None)¶

This Method returns the message data.

Parameters:: default – The default value, if no data is available.

get_data_id(default=None)¶

This Method returns the message Data-ID.

Parameters:: default – The default value, if no data is available.

get_service_id(default=None)¶

This Method returns the message Service-ID.

Parameters:: default – The default value, if no data is available.

get_status(default=None)¶

This Method returns the message status.

Parameters:: default – The default value, if no data is available.

class socket_protocol.pure_json_protocol(comm_instance, secret=None, auto_auth=False, channel_name=None)¶

This class supports to transfer a message and it’s data.

Parameters:

comm_instance (instance) – A communication instance.
secret (str) – An optinal secret (e.g. created by binascii.hexlify(os.urandom(24))).
auto_auth (bool) – An optional parameter to enable (True) automatic authentification, otherwise you need to do it manually, if needed.
channel_name (str) – An optional parameter to set a channel name for logging of the communication.

Hint

The Service-ID is designed to identify the type of the communication (e.g. READ_REQUEST, WRITE_REQUEST, READ_RESPONSE, WRITE_RESPONSE, …)
The Data-ID is designed to identify the requests / responses using the same Service_ID.

Note

The comm_instance needs to have at least the following interface:

A Method comm_instance.init_channel_name() to set the channel name.
A Constant comm_instance.IS_CLIENT to identify that the comm_instance is a client (True) or a server (False).
A Method comm_instance.is_connected() to identify if the instance is connected (True) or not (False).
A Method comm_instance.reconnect() to initiate a reconnect.
A Method comm_instance.register_callback() to register a data available callback.
A Method comm_instance.register_connect_callback() to register a connect callback.
A Method comm_instance.register_disconnect_callback() to register a disconnect callback.
A Method comm_instance.send() to send data via the comm_instance.

Note

The parameter auto_auth is only relevant, if a secret is given and the comm_instance is a client. The authentification is initiated directly after the connection is established.

Note

The channel_name-exchange will be initiated by the client directly after the the connection is established.

If a channel_name is given at both communication sides and they are different, the client name is taken over and the server will log a warning message.

Example:

import sys
sys.path.append('../..')


import report
import socket_protocol
from socket_protocol_server import example_protocol, DID_ASC_TIME
import tcp_socket
import time

if __name__ == '__main__':
    report.stdoutLoggingConfigure(log_name_lvl=[('root', 'INFO'), ])
    c = tcp_socket.tcp_client_stp('127.0.0.1', 17017)
    sp = example_protocol(c, channel_name='example_client')
    sp.send(socket_protocol.SID_READ_REQUEST, DID_ASC_TIME, None)
    print('The Client received: %s' % repr(sp.receive(socket_protocol.SID_READ_RESPONSE, 0).get_data()))

and

import sys
sys.path.append('../..')

import report
import socket_protocol
import tcp_socket
import time


DID_ASC_TIME = 0


class example_protocol(socket_protocol.pure_json_protocol):
    def __init__(self, *args, **kwargs):
        socket_protocol.pure_json_protocol.__init__(self, *args, **kwargs)
        #
        self.add_data((socket_protocol.SID_READ_REQUEST, socket_protocol.SID_READ_RESPONSE), DID_ASC_TIME, 'asc_time')
        #
        if not self.__comm_inst__.IS_CLIENT:
            self.register_callback(socket_protocol.SID_READ_REQUEST, 0, self.time_callback)

    def time_callback(self, msg):
        if msg.get_status() == socket_protocol.STATUS_OKAY:
            return socket_protocol.STATUS_OKAY, time.asctime()
        else:
            return socket_protocol.STATUS_OPERATION_NOT_PERMITTED, None


if __name__ == '__main__':
    report.stdoutLoggingConfigure(log_name_lvl=[('root', 'INFO'), ])
    s = tcp_socket.tcp_server_stp('127.0.0.1', 17017)
    sp = example_protocol(s, channel_name='example_server')

    i = 0
    while not s.is_connected() and i <= 20:
        i += 1
        time.sleep(.1)  # wait for a connection

    i = 0
    while s.is_connected() and i <= 20:
        i += 1
        time.sleep(.1)  # wait for disconnect

Will result to the following output:

2024-12-09 00:00:43,564:     INFO - socket_protocol.example_client - prot-client: Resetting authentification state to AUTH_STATE_UNTRUSTED_CONNECTION
2024-12-09 00:00:43,564:     INFO - socket_protocol.example_client - prot-client: Initialisation finished.
2024-12-09 00:00:43,564:     INFO - socket_protocol.example_client - prot-client: TX -> service: read data request, data_id: asc_time, status: okay, data: "None"
2024-12-09 00:00:43,623:     INFO - tcp_socket.example_client - comm-client: Connection established... (to 127.0.0.1:17017)
2024-12-09 00:00:43,623:     INFO - socket_protocol.example_client - prot-client: TX -> service: channel name request, data_id: name, status: okay, data: "'example_client'"
2024-12-09 00:00:43,623:     INFO - tcp_socket.example_client - comm-client: TX -> "(74): 7b 22 64 61 74 61 5f 69 64 22 3a 20 30 2c 20 22 73 65 72 76 69 63 65 5f 69 64 22 3a 20 38 2c 20 22 73 74 61 74 75 73 22 3a 20 30 2c 20 22 64 61 74 61 22 3a 20 22 65 78 61 6d 70 6c 65 5f 63 6c 69 65 6e 74 22 7d f5 cd dd e7"
2024-12-09 00:00:43,673:     INFO - tcp_socket.example_client - comm-client: TX -> "(63): 7b 22 64 61 74 61 5f 69 64 22 3a 20 30 2c 20 22 73 65 72 76 69 63 65 5f 69 64 22 3a 20 31 30 2c 20 22 73 74 61 74 75 73 22 3a 20 30 2c 20 22 64 61 74 61 22 3a 20 6e 75 6c 6c 7d 45 05 7b b4"
2024-12-09 00:00:43,674:     INFO - tcp_socket.example_client - comm-client: RX  <- "(62): 7b 22 64 61 74 61 5f 69 64 22 3a 20 30 2c 20 22 73 65 72 76 69 63 65 5f 69 64 22 3a 20 39 2c 20 22 73 74 61 74 75 73 22 3a 20 30 2c 20 22 64 61 74 61 22 3a 20 6e 75 6c 6c 7d 30 59 be 2f"
2024-12-09 00:00:43,674:     INFO - socket_protocol.example_client - prot-client: RX <- service: channel name response, data_id: name, status: okay, data: "None"
2024-12-09 00:00:43,725:     INFO - tcp_socket.example_client - comm-client: RX  <- "(85): 7b 22 64 61 74 61 5f 69 64 22 3a 20 30 2c 20 22 73 65 72 76 69 63 65 5f 69 64 22 3a 20 31 31 2c 20 22 73 74 61 74 75 73 22 3a 20 30 2c 20 22 64 61 74 61 22 3a 20 22 4d 6f 6e 20 44 65 63 20 20 39 20 30 30 3a 30 30 3a 34 33 20 32 30 32 34 22 7d 06 ef 98 ac"
2024-12-09 00:00:43,725:     INFO - socket_protocol.example_client - prot-client: RX <- service: read data response, data_id: asc_time, status: okay, data: "'Mon Dec  9 00:00:43 2024'"
The Client received: 'Mon Dec  9 00:00:43 2024'

add_data(service_id, data_id, name)¶

Method to add a name for a specific message.

Parameters:

service_id (int or list of ints) – The Service-ID of the message. See class definitions starting with SID_.
data_id (int) – The Data-ID of the message.
name (str) – The Name for the transfered message.

add_msg_to_auth_whitelist_(service_id, data_id)¶

Method to add a specific message to the list, where no authentification is required.

Parameters:

service_id (int) – The Service-ID of the message. See class definitions starting with SID_.
data_id (int) – The Data-ID of the message.

add_service(req_sid, resp_sid, req_name=None, resp_name=None)¶

Method to add a Service defined by Request- and Response Serivce-ID.

Parameters:

req_sid (int) – The Request Service-ID.
resp_sid (int) – The Response Service-ID.

add_status(status, name)¶

Method to add a name for a status.

Parameters:

status (int) – The Status. See class definitions starting with STATUS_.
name (str) – The Name for the Status.

authentificate(timeout=2)¶

This method authetificates the client at the server.

Parameters:: timeout (float) – The timeout for the authentification (requesting seed, sending key and getting authentification_feedback).
Returns:: True, if authentification was successfull; False, if not.
Return type:: bool

Note

An authentification will only processed, if a secret had been given on initialisation.

Note

Client and Server needs to use the same secret.

check_authentification_state()¶

This Method return the Authitification State as boolean value.

Returns:: True, if authentification state is okay, otherwise False
Return type:: bool

connection_established()¶

This Method returns the Connection state including authentification as a boolean value.

Returns:: True, if the connection is established (incl. authentification, if a secret has been given)
Return type:: bool

is_connected()¶

This Methods returns Connection state of the Communication Instance comm_instance.is_connected().

Returns:: True if the comm_instance is connected, otherwise False..
Return type:: bool

receive(service_id, data_id, timeout=1)¶

This Method returns a message object for a defined message or None, if this message is not available after the given timout.

Parameters:

service_id (int) – The Service-ID for the message. See class definitions starting with SID_.
data_id (int) – The Data-ID for the message.
timeout (float) – The timeout for receiving.

Returns:

The received data storage object or None, if no data was received.

Return type:

data_storage

reconnect()¶: This methods initiates a reconnect by calling comm_instance.reconnect().

register_callback(service_id, data_id, callback, *args, **kwargs)¶

This method registers a callback for the given parameters. Giving None means, that all Service-IDs or all Data-IDs are used. If a message hitting these parameters has been received, the callback will be executed.

Parameters:

service_id (int) – The Service-ID for the message. See class definitions starting with SID_.
data_id (int) – The Data-ID for the message.

Note

The callback() is priorised in the following order:

Callbacks with defined Service-ID and Data-ID.
Callbacks with a defined Service-ID and all Data-IDs.
Callbacks with a defined Data-ID and all Service-IDs.
Unspecific Callbacks.

Note

The callback() is executed with these arguments:

Parameters given at the callback call:

The first Arguments is the received message as data_storage object.
Further arguments given at registration.
Further keyword arguments given at registration.

Return value of the callback:

If the Callback is a Request Callback for a registered Service, the return value has to be a tuple or list with

response_status: The response status (see class definitions starting with STA_*.
response_data: A JSON iterable object to be used as data for the response.

Note

Only registered services will respond via the callbacks return values with the same data_id.

send(service_id, data_id, data, status=0, timeout=2)¶

This methods sends out a message with the given content.

Parameters:

service_id (int) – The Service-ID for the message. See class definitions starting with SERVICE_.
data_id (int) – The Data-ID for the message.
data (str) – The data to be transfered. The data needs to be json compatible.
status (int) – The Status for the message. All requests should have STATUS_OKAY.
timeout (float) – The timeout for sending data (e.g. time to establish new connection).

Returns:

True if data had been sent, otherwise False.

Return type:

bool

class socket_protocol.struct_json_protocol(*args, **kwargs)¶: This Class has the same functionality like pure_json_protocol. The message length is less than for pure_json_protocol, but the functionality and compatibility is reduced. See also parent pure_json_protocol.

Note

This class is depreceated and here for compatibility reasons (to support old clients or servers). Usage of pure_json_protocol is recommended.

socket_protocol (Socket Protocol)¶

Table of Contents

Previous topic

Next topic

This Page