diff --git a/.gitignore b/.gitignore index d5727dd..907a6af 100644 --- a/.gitignore +++ b/.gitignore @@ -5,6 +5,7 @@ tests/*/__pycache__/ *.#* *# *~ +docs/_build /build /dist /electrumx.egg-info diff --git a/docs/protocol-changes.rst b/docs/protocol-changes.rst index 10f5288..7acb856 100644 --- a/docs/protocol-changes.rst +++ b/docs/protocol-changes.rst @@ -58,6 +58,7 @@ New methods * :func:`blockchain.block.headers` * :func:`mempool.get_fee_histogram` + * :func:`server.ping` Deprecated methods ------------------ diff --git a/docs/protocol-methods.rst b/docs/protocol-methods.rst index 925c333..cb5ed7e 100644 --- a/docs/protocol-methods.rst +++ b/docs/protocol-methods.rst @@ -745,8 +745,8 @@ Return the address paid to by a UTXO. mempool.get_fee_histogram ------------------------- - Return a histogram of the fee rates paid by transactions in the - memory pool, weighted by transaction size. +Return a histogram of the fee rates paid by transactions in the memory +pool, weighted by transaction size. **Signature** @@ -776,8 +776,8 @@ mempool.get_fee_histogram server.add_peer --------------- - This call is intended for a new server to get itself into a server's - peers list, and should not be used by wallet clients. +A newly-started server uses this call to get itself into other servers' +peers lists. It sould not be used by wallet clients. **Signature** @@ -800,7 +800,7 @@ server.add_peer server.banner ------------- - Return a banner to be shown in the Electrum console. +Return a banner to be shown in the Electrum console. **Signature** @@ -820,7 +820,7 @@ server.banner server.donation_address ----------------------- - Return a server donation address. +Return a server donation address. **Signature** @@ -840,7 +840,7 @@ server.donation_address server.features --------------- - Return a list of features and services supported by the server. +Return a list of features and services supported by the server. **Signature** @@ -949,17 +949,35 @@ server.peers.subscribe the default port for the coin network is implied. If 's' or 't' is missing then the server does not support that transport. +server.ping +----------- + +Ping the server to ensure it is responding, and to keep the session +alive. The server may disconnect clients that have sent no requests +for roughly 10 minutes. + +**Signature** + + .. function:: server.ping() + .. versionadded:: 1.2 + +**Result** + + Returns :const:`null`. server.version -------------- - Identify the client to the server and negotiate the protocol version. +Identify the client to the server and negotiate the protocol version. **Signature** .. function:: server.version(client_name="", protocol_version="1.1") .. versionchanged:: 1.1 *protocol_version* is not ignored. + .. versionchanged:: 1.2 + Use :func:`server.ping` rather than sending version requests as a + ping mechanism. * *client_name* diff --git a/server/session.py b/server/session.py index e24f728..fbf4865 100644 --- a/server/session.py +++ b/server/session.py @@ -329,6 +329,12 @@ class ElectrumX(SessionBase): return banner + def ping(self): + '''Serves as a connection keep-alive mechanism and for the client to + confirm the server is still responding. + ''' + return None + def server_version(self, client_name=None, protocol_version=None): '''Returns the server version as a string. @@ -463,6 +469,7 @@ class ElectrumX(SessionBase): 'mempool.get_fee_histogram': controller.mempool_get_fee_histogram, 'blockchain.block.headers': self.block_headers, + 'server.ping': self.ping, }) self.electrumx_handlers = handlers