Part of twisted.internet View Source
IStreamServerEndpoint
and IStreamClientEndpoint
that wrap the IReactorTCP
,
IReactorSSL
,
and IReactorUNIX
interfaces.
This also implements an extensible mini-language for describing
endpoints, parsed by the clientFromString
and serverFromString
functions.
Present Since | 10.1 |
Interface | IPlugin | Undocumented |
Class | StandardIOEndpoint | A Standard Input/Output endpoint |
Class | StandardErrorBehavior | Constants used in ProcessEndpoint to decide what to do with stderr. |
Class | ProcessEndpoint | An endpoint for child processes |
Class | TCP4ServerEndpoint | Implements TCP server endpoint with an IPv4 configuration |
Class | TCP6ServerEndpoint | Implements TCP server endpoint with an IPv6 configuration |
Class | TCP4ClientEndpoint | TCP client endpoint with an IPv4 configuration. |
Class | TCP6ClientEndpoint | TCP client endpoint with an IPv6 configuration. |
Class | HostnameEndpoint | A name-based endpoint that connects to the fastest amongst the resolved host addresses. |
Class | SSL4ServerEndpoint | SSL secured TCP server endpoint with an IPv4 configuration. |
Class | SSL4ClientEndpoint | SSL secured TCP client endpoint with an IPv4 configuration |
Class | UNIXServerEndpoint | UnixSocket server endpoint. |
Class | UNIXClientEndpoint | UnixSocket client endpoint. |
Class | AdoptedStreamServerEndpoint | An endpoint for listening on a file descriptor initialized outside of Twisted. |
Function | serverFromString | Construct a stream server endpoint from an endpoint description string. |
Function | quoteStringArgument | No summary |
Function | clientFromString | Construct a client endpoint from a description string. |
Function | connectProtocol | Connect a protocol instance to an endpoint. |
Class | _WrappingProtocol | Wrap another protocol in order to notify my user when a connection has been made. |
Class | _WrappingFactory | Wrap a factory in order to wrap the protocols it builds. |
Class | _ProcessEndpointTransport | An ITransport
provider for the IProtocol
instance passed to the process endpoint. |
Class | _WrapIProtocol | An IProcessProtocol
provider that wraps an IProtocol . |
Class | _TCPServerEndpoint | A TCP server endpoint interface |
Function | _parseTCP | Internal parser function for _parseServer
to convert the string arguments for a TCP(IPv4) stream endpoint into the
structured arguments. |
Function | _parseUNIX | Internal parser function for _parseServer
to convert the string arguments for a UNIX (AF_UNIX/SOCK_STREAM) stream
endpoint into the structured arguments. |
Function | _parseSSL | Internal parser function for _parseServer
to convert the string arguments for an SSL (over TCP/IPv4) stream endpoint
into the structured arguments. |
Class | _StandardIOParser | Stream server endpoint string parser for the Standard I/O type. |
Class | _SystemdParser | Stream server endpoint string parser for the systemd endpoint type. |
Class | _TCP6ServerParser | Stream server endpoint string parser for the TCP6ServerEndpoint type. |
Function | _tokenize | Tokenize a strports string and yield each token. |
Function | _parse | Convert a description string into a list of positional and keyword parameters, using logic vaguely like what Python does. |
Function | _parseServer | Parse a strports description into a 2-tuple of arguments and keyword values. |
Function | _serverFromStringLegacy | Underlying implementation of serverFromString
which avoids exposing the deprecated 'default' argument to anything but strports.service . |
Function | _parseClientTCP | Perform any argument value coercion necessary for TCP client parameters. |
Function | _loadCAsFromDir | Load certificate-authority certificate objects in a given directory. |
Function | _parseClientSSL | Perform any argument value coercion necessary for SSL client parameters. |
Function | _parseClientUNIX | Perform any argument value coercion necessary for UNIX client parameters. |
_parseServer
to convert the string arguments for a TCP(IPv4) stream endpoint into the
structured arguments.Parameters | factory | the protocol factory being parsed, or None . (This was a
leftover argument from when this code was in strports , and is
now mostly None and unused.) (type: IProtocolFactory
or NoneType ) |
port | the integer port number to bind (type: str ) | |
interface | the interface IP to listen on | |
backlog | the length of the listen queue (type: str ) | |
Returns | a 2-tuple of (args, kwargs), describing the parameters to IReactorTCP.listenTCP
(or, modulo argument 2, the factory, arguments to TCP4ServerEndpoint . |
_parseServer
to convert the string arguments for a UNIX (AF_UNIX/SOCK_STREAM) stream
endpoint into the structured arguments.Parameters | factory | the protocol factory being parsed, or None . (This was a
leftover argument from when this code was in strports , and is
now mostly None and unused.) (type: IProtocolFactory
or NoneType ) |
address | the pathname of the unix socket (type: str ) | |
backlog | the length of the listen queue (type: str ) | |
lockfile | A string '0' or '1', mapping to True and False respectively. See the
wantPID argument to listenUNIX | |
Returns | a 2-tuple of (args, kwargs), describing the parameters to
IReactorTCP.listenUNIX (or, modulo argument 2, the factory,
arguments to UNIXServerEndpoint . |
_parseServer
to convert the string arguments for an SSL (over TCP/IPv4) stream endpoint
into the structured arguments.Parameters | factory | the protocol factory being parsed, or None . (This was a
leftover argument from when this code was in strports , and is
now mostly None and unused.) (type: IProtocolFactory
or NoneType ) |
port | the integer port number to bind (type: str ) | |
interface | the interface IP to listen on | |
backlog | the length of the listen queue (type: str ) | |
privateKey | The file name of a PEM format private key file. (type: str ) | |
certKey | The file name of a PEM format certificate file. (type: str ) | |
sslmethod | The string name of an SSL method, based on the name of a constant in
OpenSSL.SSL . Must be one of: "SSLv23_METHOD",
"SSLv2_METHOD", "SSLv3_METHOD",
"TLSv1_METHOD". (type: str ) | |
extraCertChain | The path of a file containing one or more certificates in PEM format that
establish the chain from a root CA to the CA that signed your
certKey . (type: bytes ) | |
dhParameters | The file name of a file containing parameters that are required for
Diffie-Hellman key exchange. If this is not specified, the forward secret
DHE ciphers aren't available for servers. (type: bytes ) | |
Returns | a 2-tuple of (args, kwargs), describing the parameters to IReactorSSL.listenSSL
(or, modulo argument 2, the factory, arguments to SSL4ServerEndpoint . |
Parameters | description | a string as described by serverFromString
or clientFromString . |
Returns | an iterable of 2-tuples of (_OP or _STRING ,
string). Tuples starting with _OP will contain a second
element of either ':' (i.e. 'next parameter') or '=' (i.e. 'assign
parameter value'). For example, the string 'hello:greet\=ing=world' would
result in a generator yielding these values:
_STRING, 'hello' _OP, ':' _STRING, 'greet=ing' _OP, '=' _STRING, 'world' |
Parameters | description | a string as described by serverFromString
or clientFromString . |
Returns | a 2-tuple of (args, kwargs) , where 'args' is a list of all
':'-separated str s not containing an '=' and 'kwargs' is a map
of all str s which do contain an '='. For example, the result
of _parse('a:b:d=1:c') would be (['a', 'b', 'c'], {'d':
'1'}) . |
Parameters | description | A description in the format explained by serverFromString . (type: str ) |
factory | A 'factory' argument; this is left-over from twisted.application.strports,
it's not really used. (type: IProtocolFactory
or None ) | |
default | Deprecated argument, specifying the default parser mode to use for
unqualified description strings (those which do not have a ':' and prefix). (type: str or NoneType ) | |
Returns | a 3-tuple of (plugin or name, arguments, keyword arguments) |
serverFromString
which avoids exposing the deprecated 'default' argument to anything but strports.service
.The format for server endpoint descriptions is a simple byte string. It is a prefix naming the type of endpoint, then a colon, then the arguments for that endpoint.
For example, you can call it like this to create an endpoint that will listen on TCP port 80:
serverFromString(reactor, b"tcp:80")
Additional arguments may be specified as keywords, separated with colons. For example, you can specify the interface for a TCP server endpoint to bind to like this:
serverFromString(reactor, b"tcp:80:interface=127.0.0.1")
SSL server endpoints may be specified with the 'ssl' prefix, and the
private key and certificate files may be specified by the
privateKey
and certKey
arguments:
serverFromString( reactor, b"ssl:443:privateKey=key.pem:certKey=crt.pem")
If a private key file name (privateKey
) isn't provided, a
"server.pem" file is assumed to exist which contains the private
key. If the certificate file name (certKey
) isn't provided,
the private key file is assumed to contain the certificate as well.
You may escape colons in arguments with a backslash, which you will need to use if you want to specify a full pathname argument on Windows:
serverFromString(reactor, b"ssl:443:privateKey=C\:/key.pem:certKey=C\:/cert.pem")
finally, the 'unix' prefix may be used to specify a filesystem UNIX
socket, optionally with a 'mode' argument to specify the mode of the socket
file created by listen
:
serverFromString(reactor, b"unix:/var/run/finger") serverFromString(reactor, b"unix:/var/run/finger:mode=660")
This function is also extensible; new endpoint types may be registered
as IStreamServerEndpointStringParser
plugins. See that interface for more information.
Parameters | reactor | The server endpoint will be constructed with this reactor. |
description | The strports description to parse. (type: bytes ) | |
Returns | A new endpoint which can be used to listen with the parameters given by by
description . (type: IStreamServerEndpoint ) | |
Raises | ValueError | when the 'description' string cannot be parsed. |
Present Since | 10.2 |
Quote an argument to serverFromString
and clientFromString
.
Since arguments are separated with colons and colons are escaped with
backslashes, some care is necessary if, for example, you have a pathname,
you may be tempted to interpolate into a string like this:
serverFromString(reactor, b"ssl:443:privateKey=%s" % (myPathName,))
This may appear to work, but will have portability issues (Windows
pathnames, for example). Usually you should just construct the appropriate
endpoint type rather than interpolating strings, which in this case would
be SSL4ServerEndpoint
.
There are some use-cases where you may need to generate such a string,
though; for example, a tool to manipulate a configuration file which has
strports descriptions in it. To be correct in those cases, do this
instead:
serverFromString(reactor, b"ssl:443:privateKey=%s" % (quoteStringArgument(myPathName),))
Parameters | argument | The part of the endpoint description string you want to pass through. (type: bytes ) |
Returns | The quoted argument. (type: bytes ) |
Valid positional arguments to this function are host and port.
Valid keyword arguments to this function are all IReactorTCP.connectTCP
arguments.
Returns | The coerced values as a dict . |
Parameters | directoryPath | a FilePath
pointing at a directory to load .pem files from. |
Returns | a list of OpenSSL.crypto.X509 objects. |
Valid keyword arguments to this function are all IReactorSSL.connectSSL
arguments except for contextFactory
. Instead,
certKey
(the path name of the certificate file)
privateKey
(the path name of the private key associated with
the certificate) are accepted and used to construct a context factory.
Valid positional arguments to this function are host and port.
Parameters | caCertsDir | The one parameter which is not part of IReactorSSL.connectSSL 's
signature, this is a path name used to construct a list of certificate
authority certificates. The directory will be scanned for files ending in
.pem , all of which will be considered valid certificate
authorities for this connection. (type: str ) |
Returns | The coerced values as a dict . |
Valid keyword arguments to this function are all IReactorUNIX.connectUNIX
keyword arguments except for checkPID
. Instead,
lockfile
is accepted and has the same meaning. Also
path
is used instead of address
.
Valid positional arguments to this function are path
.
Returns | The coerced values as a dict . |
Client description strings are much like server description strings, although they take all of their arguments as keywords, aside from host and port.
You can create a TCP client endpoint with the 'host' and 'port' arguments, like so:
clientFromString(reactor, b"tcp:host=www.example.com:port=80")
or, without specifying host and port keywords:
clientFromString(reactor, b"tcp:www.example.com:80")
Or you can specify only one or the other, as in the following 2 examples:
clientFromString(reactor, b"tcp:host=www.example.com:80") clientFromString(reactor, b"tcp:www.example.com:port=80")
or an SSL client endpoint with those arguments, plus the arguments used by the server SSL, for a client certificate:
clientFromString(reactor, b"ssl:web.example.com:443:" b"privateKey=foo.pem:certKey=foo.pem")
to specify your certificate trust roots, you can identify a directory
with PEM files in it with the caCertsDir
argument:
clientFromString(reactor, b"ssl:host=web.example.com:port=443:" b"caCertsDir=/etc/ssl/certs")
Both TCP and SSL client endpoint description strings can include a 'bindAddress' keyword argument, whose value should be a local IPv4 address. This fixes the client socket to that IP address:
clientFromString(reactor, b"tcp:www.example.com:80:" b"bindAddress=192.0.2.100")
NB: Fixed client ports are not currently supported in TCP or SSL client endpoints. The client socket will always use an ephemeral port assigned by the operating system
You can create a UNIX client endpoint with the 'path' argument and optional 'lockfile' and 'timeout' arguments:
clientFromString( reactor, b"unix:path=/var/foo/bar:lockfile=1:timeout=9")
or, with the path as a positional argument with or without optional arguments as in the following 2 examples:
clientFromString(reactor, b"unix:/var/foo/bar") clientFromString(reactor, b"unix:/var/foo/bar:lockfile=1:timeout=9")
This function is also extensible; new endpoint types may be registered
as IStreamClientEndpointStringParserWithReactor
plugins. See that interface for more information.
Parameters | reactor | The client endpoint will be constructed with this reactor. |
description | The strports description to parse. (type: bytes ) | |
Returns | A new endpoint which can be used to connect with the parameters given by by
description . (type: IStreamClientEndpoint ) | |
Present Since | 10.2 |
This allows using a client endpoint without having to create a factory.
Parameters | endpoint | A client endpoint to connect to. |
protocol | A protocol instance. | |
Returns | The result of calling connect on the endpoint, i.e. a Deferred that
will fire with the protocol when connected, or an appropriate error. | |
Present Since | 13.1 |