hio.core.tcp.serving ==================== .. py:module:: hio.core.tcp.serving .. autoapi-nested-parse:: hio.core.tcp.serving Module Accepter listens and accepts incoming TCP socket connections Server is subclass of Acceptor Server creates Remoters Remoter is accepted incoming socket connection ServerTls is subclass of Server RemoterTls is subclass of Remoter Module Contents --------------- .. py:function:: openServer(cls=None, **kwa) Wrapper to create and open TCP Server instances When used in with statement block, calls .close() on exit of with block :param cls is Class instance of subclass instance: Usage:: with openServer() as server0: server0. with openServer(cls=ServerTls) as server0: server0. .. py:class:: Acceptor(ha=None, bs=8096, bl=128, **kwa) Bases: :py:obj:`hio.base.tyming.Tymee` Acceptor Base Class for Server. Nonblocking TCP Socket Acceptor Class. Listen socket for incoming TCP connections See tyming.Tymee for inherited attributes, properties, and methods .. attribute:: .ha is host = "" or "0.0.0.0" means listen on all interfaces :type: host,port) duple (two tuple .. attribute:: .eha is normalized as external facing address for TLS context :type: host, port .. attribute:: .bs is buffer size .. attribute:: .ss is server listen socket for incoming accept requests .. attribute:: .axes is deque of accepte connection duples :type: ca, cs .. attribute:: .opened is boolean, True if listen socket .ss opened. False otherwise .. py:method:: actualBufSizes() Returns duple of the the actual socket send and receive buffer size (send, receive) .. py:method:: open() Opens binds listen socket in non blocking mode. if socket not closed properly, binding socket gets error OSError: (48, 'Address already in use') .. py:method:: reopen(**kwa) Idempotently opens listen socket .. py:method:: close() Closes listen socket. .. py:method:: accept() Accept new connection nonblocking Returns duple (cs, ca) of connected socket and connected host address Otherwise if no new connection returns (None, None) .. py:method:: serviceAccepts() Service any accept requests Adds to .cxes dict key by ca .. py:class:: Server(ha=None, host='', port=56000, tymeout=None, wl=None, **kwa) Bases: :py:obj:`Acceptor` Nonblocking TCP Socket Server Class. Listen socket for incoming TCP connections that generates Remoter sockets for accepted connections See tyming.Tymee for inherited attributes, properties, and methods Inherited Attributes: ha (tuple[str, int]): (host, port) duple; host = "" or "0.0.0.0" means listen on all interfaces eha (tuple[str, int]): normalized external-facing (host, port) for TLS context bs (int): buffer size ss (socket.socket | None): server listen socket for incoming accept requests axes (deque): accepted connection duples (ca, cs) opened (bool): True if listen socket ss is open; False otherwise .. attribute:: tymeout timeout in seconds for connection refresh :type: float .. attribute:: wl WireLog instance if any :type: WireLog | None .. attribute:: ixes incoming connections indexed by remote (host, port) duple :type: dict .. py:method:: wind(tymth) Inject new tymist.tymth as new ._tymth. Changes tymist.tyme base. Updates winds .tymer .tymth .. py:method:: serviceAxes() Service axes For each newly accepted connection in .axes create Remoter and add to .ixes keyed by ca .. py:method:: serviceConnects() Service connects is method name to be used .. py:method:: shutdownIx(ca, how=socket.SHUT_RDWR) Shutdown remoter given by connection address ca .. py:method:: shutdownSendIx(ca) Shutdown send on remoter given by connection address ca .. py:method:: shutdownReceiveIx(ca) Shutdown send on remoter given by connection address ca .. py:method:: closeIx(ca) Shutdown and close remoter given by connection address ca .. py:method:: closeAllIx() Shutdown and close all remoter connections .. py:method:: close() Close all sockets .. py:method:: removeIx(ca, close=True) Remove remoter given by connection address ca .. py:method:: serviceReceivesIx(ca) Service receives for remoter by connection address ca .. py:method:: serviceReceivesAllIx() Service receives for all remoters in .ixes .. py:method:: transmitIx(data, ca) Queue data onto .txbs for remoter given by connection address ca .. py:method:: serviceSendsAllIx() Service transmits for all remoters in .ixes .. py:method:: service() Service connects and service receives and sends for all ix. .. py:function:: initServerContext(context=None, version=None, certify=None, keypath=None, certpath=None, cafilepath=None) Initialize and return context for TLS Server IF context is None THEN create a context IF version is None THEN create context using ssl library default ELSE create context with version If certify is not None then use certify value provided Otherwise use default context is the tls/ssl context object; if None use default. version is ssl protocol version; if None use default. certify is cert requirement; if None use default (ssl.CERT_NONE, ssl.CERT_OPTIONAL, ssl.CERT_REQUIRED). keypath is local server PKI private key file path; if given apply to context. certpath is local server PKI public cert file path; if given apply to context. cafilepath is cert authority file path to verify client cert; if given apply. .. py:class:: ServerTls(context=None, version=None, certify=None, keypath=None, certpath=None, cafilepath=None, **kwa) Bases: :py:obj:`Server` Server with Nonblocking TLS/SSL support Nonblocking TCP Socket Server Class. Listen socket for incoming TCP connections RemoterTLS sockets for accepted connections See tyming.Tymee for inherited attributes, properties, and methods Inherited Attributes: ha (tuple[str, int]): (host, port) duple; host = "" or "0.0.0.0" means listen on all interfaces eha (tuple[str, int]): normalized external-facing (host, port) for TLS context bs (int): buffer size ss (socket.socket | None): server listen socket for incoming accept requests axes (deque): accepted connection duples (ca, cs) opened (bool): True if listen socket ss is open; False otherwise timeout (float): timeout in seconds for connection refresh wl (WireLog | None): WireLog instance if any ixes (dict): incoming connections indexed by remote (host, port) duple .. attribute:: context TLS context instance :type: ssl.SSLContext | None .. attribute:: version TLS version :type: int | None .. attribute:: certify True to require client cert verification :type: bool | None .. attribute:: keypath path to key file :type: str | None .. attribute:: certpath path to cert file :type: str | None .. attribute:: cafilepath path to CA file :type: str | None .. py:method:: serviceAxes() Service accepteds For each new accepted connection create RemoterTLS and add to .cxes Not Handshaked .. py:method:: serviceCxes() Service handshakes for every remoter in .cxes If successful move to .ixes .. py:method:: serviceConnects() Service accept and handshake attempts For each successful handshake add to .ixes. .. py:class:: Remoter(ha, ca, cs, tymeout=None, refreshable=True, bs=8096, wl=None, **kwa) Bases: :py:obj:`hio.base.tyming.Tymee` Class to service an incoming nonblocking TCP connection from a remote client. Should only be used by an Acceptor subclass such as Server .. py:method:: wind(tymth) Inject new tymist.tymth as new ._tymth. Changes tymist.tyme base. Updates winds .tymer .tymth .. py:method:: shutdown(how=socket.SHUT_RDWR) Shutdown connected socket .cs .. py:method:: shutdownSend() Shutdown send on connected socket .cs .. py:method:: shutdownReceive() Shutdown receive on connected socket .cs .. py:method:: close() Shutdown and close connected socket .cs .. py:method:: refresh() Restart tymer .. py:method:: receive() Perform non blocking receive on connected socket .cs If no data then returns None If connection closed then returns '' Otherwise returns data data is string in python2 and bytes in python3 .. py:method:: serviceReceives() Service receives until no more .. py:method:: serviceReceiveOnce() Retrieve from server only one reception .. py:method:: clearRxbs() Clear .rxbs .. py:method:: send(data) Perform non blocking send on connected socket .cs. Return number of bytes sent data is string in python2 and bytes in python3 .. py:method:: tx(data) Queue data onto .txbs .. py:method:: serviceSends() Service transmits For each tx if all bytes sent then keep sending until partial send or no more to send If partial send reattach and return .. py:class:: RemoterTls(context=None, version=None, certify=None, keypath=None, certpath=None, cafilepath=None, **kwa) Bases: :py:obj:`Remoter` Class to service an incoming nonblocking TCP/TLS connection from a remote client. Should only be used from Acceptor subclass Provides nonblocking TLS/SSL support .. attribute:: connected True means TLS handshake completed False otherwise :type: bool .. attribute:: aborted True means client aborted TLS handshake False otherwise :type: bool .. py:method:: close() Shutdown and close connected socket .cs .. py:method:: wrap() Wrap socket .cs in ssl context .. py:method:: handshake() Attempt nonblocking ssl handshake to .ha Sets .connected when complete successfully Sets .aborted when client terminates prematurely Keep trying while not connected and not aborted .. py:method:: receive() Perform non blocking receive on connected socket .cs If no data then returns None If connection closed then returns '' Otherwise returns data data is string in python2 and bytes in python3 .. py:method:: send(data) Perform non blocking send on connected socket .cs. Return number of bytes sent data is string in python2 and bytes in python3 .. py:class:: ServerDoer(server, **kwa) Bases: :py:obj:`hio.base.doing.Doer` Basic TCP Server Doer See Doer for inherited attributes, properties, and methods. .. attribute:: .server is TCP Server instance Properties: .. py:method:: wind(tymth) Inject new tymist.tymth as new ._tymth. Changes tymist.tyme base. Updates winds .tymer .tymth .. py:method:: enter(*, temp=None) Do 'enter' context actions. Override in subclass. Not a generator method. Set up resources. Comparable to context manager enter. :param temp: True means use temporary file resources if any None means ignore parameter value. Use self.temp :type temp: bool | None Inject temp or self.temp into file resources here if any Doist or DoDoer winds its doers on enter .. py:method:: recur(tyme) Do 'recur' context actions. Override in subclass. Regular method that perform repetitive actions once per invocation. Assumes resource setup in .enter() and resource takedown in .exit() (see ReDoer below for example of .recur that is a generator method) Returns completion state of recurrence actions: True means done, False means continue. Doist provides the time value. .recur maybe implemented by a subclass either as a non-generator method or a generator method. This stub here is as a non-generator method. The base class .do detects which type:: If non-generator .do method runs .recur method once per iteration until .recur returns (True) If generator .do method runs .recur with (yield from) until .recur returns (see ReDoer for example of generator .recur) .. py:method:: exit() Do 'exit' context actions. Override in subclass. Not a generator method. Clean up resources. Comparable to context manager exit. Called by finally after normal return, close, or abort. After .exit() do returns resulting in StopIteration. .. py:class:: EchoServerDoer(server, **kwa) Bases: :py:obj:`ServerDoer` Echo TCP Server Just echoes back to client whatever it receives from client See Doer for inherited attributes, properties, and methods. Inherited Attributes: .server is TCP Server instance .. py:method:: recur(tyme) Do 'recur' context actions. Override in subclass. Regular method that perform repetitive actions once per invocation. Assumes resource setup in .enter() and resource takedown in .exit() (see ReDoer below for example of .recur that is a generator method) Returns completion state of recurrence actions: True means done, False means continue. Doist provides the time value. .recur maybe implemented by a subclass either as a non-generator method or a generator method. This stub here is as a non-generator method. The base class .do detects which type:: If non-generator .do method runs .recur method once per iteration until .recur returns (True) If generator .do method runs .recur with (yield from) until .recur returns (see ReDoer for example of generator .recur) .. py:method:: exit() Do 'exit' context actions. Override in subclass. Not a generator method. Clean up resources. Comparable to context manager exit. Called by finally after normal return, close, or abort. After .exit() do returns resulting in StopIteration.