Funktionierender Prototyp des Serious Games zur Vermittlung von Wissen zu Software-Engineering-Arbeitsmodellen.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

endpoints.py 76KB

1 year ago
1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065206620672068206920702071207220732074207520762077207820792080208120822083208420852086208720882089209020912092209320942095209620972098209921002101210221032104210521062107210821092110211121122113211421152116211721182119212021212122212321242125212621272128212921302131213221332134213521362137213821392140214121422143214421452146214721482149215021512152215321542155215621572158215921602161216221632164216521662167216821692170217121722173217421752176217721782179218021812182218321842185218621872188218921902191219221932194219521962197219821992200220122022203220422052206220722082209221022112212221322142215221622172218221922202221222222232224222522262227222822292230223122322233223422352236223722382239224022412242224322442245224622472248224922502251225222532254225522562257225822592260226122622263226422652266226722682269227022712272227322742275227622772278227922802281228222832284228522862287228822892290229122922293229422952296229722982299230023012302230323042305230623072308230923102311231223132314231523162317231823192320232123222323232423252326232723282329233023312332233323342335
  1. # -*- test-case-name: twisted.internet.test.test_endpoints -*-
  2. # Copyright (c) Twisted Matrix Laboratories.
  3. # See LICENSE for details.
  4. """
  5. Implementations of L{IStreamServerEndpoint} and L{IStreamClientEndpoint} that
  6. wrap the L{IReactorTCP}, L{IReactorSSL}, and L{IReactorUNIX} interfaces.
  7. This also implements an extensible mini-language for describing endpoints,
  8. parsed by the L{clientFromString} and L{serverFromString} functions.
  9. @since: 10.1
  10. """
  11. import os
  12. import re
  13. import socket
  14. import warnings
  15. from typing import Optional
  16. from unicodedata import normalize
  17. from zope.interface import directlyProvides, implementer, provider
  18. from constantly import NamedConstant, Names # type: ignore[import]
  19. from incremental import Version
  20. from twisted.internet import defer, error, fdesc, interfaces, threads
  21. from twisted.internet.abstract import isIPAddress, isIPv6Address
  22. from twisted.internet.address import (
  23. HostnameAddress,
  24. IPv4Address,
  25. IPv6Address,
  26. _ProcessAddress,
  27. )
  28. from twisted.internet.interfaces import (
  29. IHostnameResolver,
  30. IReactorPluggableNameResolver,
  31. IReactorSocket,
  32. IResolutionReceiver,
  33. IStreamClientEndpointStringParserWithReactor,
  34. IStreamServerEndpointStringParser,
  35. )
  36. from twisted.internet.protocol import ClientFactory, Factory, ProcessProtocol, Protocol
  37. try:
  38. from twisted.internet.stdio import PipeAddress, StandardIO
  39. except ImportError:
  40. # fallback if pywin32 is not installed
  41. StandardIO = None # type: ignore[assignment,misc]
  42. PipeAddress = None # type: ignore[assignment,misc]
  43. from twisted.internet._resolver import HostResolution
  44. from twisted.internet.defer import Deferred
  45. from twisted.internet.task import LoopingCall
  46. from twisted.logger import Logger
  47. from twisted.plugin import IPlugin, getPlugins
  48. from twisted.python import deprecate, log
  49. from twisted.python.compat import _matchingString, iterbytes, nativeString
  50. from twisted.python.components import proxyForInterface
  51. from twisted.python.failure import Failure
  52. from twisted.python.filepath import FilePath
  53. from twisted.python.systemd import ListenFDs
  54. from ._idna import _idnaBytes, _idnaText
  55. try:
  56. from OpenSSL.SSL import Error as SSLError
  57. from twisted.internet.ssl import (
  58. Certificate,
  59. CertificateOptions,
  60. KeyPair,
  61. PrivateCertificate,
  62. optionsForClientTLS,
  63. trustRootFromCertificates,
  64. )
  65. from twisted.protocols.tls import TLSMemoryBIOFactory as _TLSMemoryBIOFactory
  66. except ImportError:
  67. TLSMemoryBIOFactory = None
  68. else:
  69. TLSMemoryBIOFactory = _TLSMemoryBIOFactory
  70. __all__ = [
  71. "clientFromString",
  72. "serverFromString",
  73. "TCP4ServerEndpoint",
  74. "TCP6ServerEndpoint",
  75. "TCP4ClientEndpoint",
  76. "TCP6ClientEndpoint",
  77. "UNIXServerEndpoint",
  78. "UNIXClientEndpoint",
  79. "SSL4ServerEndpoint",
  80. "SSL4ClientEndpoint",
  81. "AdoptedStreamServerEndpoint",
  82. "StandardIOEndpoint",
  83. "ProcessEndpoint",
  84. "HostnameEndpoint",
  85. "StandardErrorBehavior",
  86. "connectProtocol",
  87. "wrapClientTLS",
  88. ]
  89. class _WrappingProtocol(Protocol):
  90. """
  91. Wrap another protocol in order to notify my user when a connection has
  92. been made.
  93. """
  94. def __init__(self, connectedDeferred, wrappedProtocol):
  95. """
  96. @param connectedDeferred: The L{Deferred} that will callback
  97. with the C{wrappedProtocol} when it is connected.
  98. @param wrappedProtocol: An L{IProtocol} provider that will be
  99. connected.
  100. """
  101. self._connectedDeferred = connectedDeferred
  102. self._wrappedProtocol = wrappedProtocol
  103. for iface in [
  104. interfaces.IHalfCloseableProtocol,
  105. interfaces.IFileDescriptorReceiver,
  106. interfaces.IHandshakeListener,
  107. ]:
  108. if iface.providedBy(self._wrappedProtocol):
  109. directlyProvides(self, iface)
  110. def logPrefix(self):
  111. """
  112. Transparently pass through the wrapped protocol's log prefix.
  113. """
  114. if interfaces.ILoggingContext.providedBy(self._wrappedProtocol):
  115. return self._wrappedProtocol.logPrefix()
  116. return self._wrappedProtocol.__class__.__name__
  117. def connectionMade(self):
  118. """
  119. Connect the C{self._wrappedProtocol} to our C{self.transport} and
  120. callback C{self._connectedDeferred} with the C{self._wrappedProtocol}
  121. """
  122. self._wrappedProtocol.makeConnection(self.transport)
  123. self._connectedDeferred.callback(self._wrappedProtocol)
  124. def dataReceived(self, data):
  125. """
  126. Proxy C{dataReceived} calls to our C{self._wrappedProtocol}
  127. """
  128. return self._wrappedProtocol.dataReceived(data)
  129. def fileDescriptorReceived(self, descriptor):
  130. """
  131. Proxy C{fileDescriptorReceived} calls to our C{self._wrappedProtocol}
  132. """
  133. return self._wrappedProtocol.fileDescriptorReceived(descriptor)
  134. def connectionLost(self, reason):
  135. """
  136. Proxy C{connectionLost} calls to our C{self._wrappedProtocol}
  137. """
  138. return self._wrappedProtocol.connectionLost(reason)
  139. def readConnectionLost(self):
  140. """
  141. Proxy L{IHalfCloseableProtocol.readConnectionLost} to our
  142. C{self._wrappedProtocol}
  143. """
  144. self._wrappedProtocol.readConnectionLost()
  145. def writeConnectionLost(self):
  146. """
  147. Proxy L{IHalfCloseableProtocol.writeConnectionLost} to our
  148. C{self._wrappedProtocol}
  149. """
  150. self._wrappedProtocol.writeConnectionLost()
  151. def handshakeCompleted(self):
  152. """
  153. Proxy L{interfaces.IHandshakeListener} to our
  154. C{self._wrappedProtocol}.
  155. """
  156. self._wrappedProtocol.handshakeCompleted()
  157. class _WrappingFactory(ClientFactory):
  158. """
  159. Wrap a factory in order to wrap the protocols it builds.
  160. @ivar _wrappedFactory: A provider of I{IProtocolFactory} whose buildProtocol
  161. method will be called and whose resulting protocol will be wrapped.
  162. @ivar _onConnection: A L{Deferred} that fires when the protocol is
  163. connected
  164. @ivar _connector: A L{connector <twisted.internet.interfaces.IConnector>}
  165. that is managing the current or previous connection attempt.
  166. """
  167. # Type is wrong. See https://twistedmatrix.com/trac/ticket/10005#ticket
  168. protocol = _WrappingProtocol # type: ignore[assignment]
  169. def __init__(self, wrappedFactory):
  170. """
  171. @param wrappedFactory: A provider of I{IProtocolFactory} whose
  172. buildProtocol method will be called and whose resulting protocol
  173. will be wrapped.
  174. """
  175. self._wrappedFactory = wrappedFactory
  176. self._onConnection = defer.Deferred(canceller=self._canceller)
  177. def startedConnecting(self, connector):
  178. """
  179. A connection attempt was started. Remember the connector which started
  180. said attempt, for use later.
  181. """
  182. self._connector = connector
  183. def _canceller(self, deferred):
  184. """
  185. The outgoing connection attempt was cancelled. Fail that L{Deferred}
  186. with an L{error.ConnectingCancelledError}.
  187. @param deferred: The L{Deferred <defer.Deferred>} that was cancelled;
  188. should be the same as C{self._onConnection}.
  189. @type deferred: L{Deferred <defer.Deferred>}
  190. @note: This relies on startedConnecting having been called, so it may
  191. seem as though there's a race condition where C{_connector} may not
  192. have been set. However, using public APIs, this condition is
  193. impossible to catch, because a connection API
  194. (C{connectTCP}/C{SSL}/C{UNIX}) is always invoked before a
  195. L{_WrappingFactory}'s L{Deferred <defer.Deferred>} is returned to
  196. C{connect()}'s caller.
  197. @return: L{None}
  198. """
  199. deferred.errback(
  200. error.ConnectingCancelledError(self._connector.getDestination())
  201. )
  202. self._connector.stopConnecting()
  203. def doStart(self):
  204. """
  205. Start notifications are passed straight through to the wrapped factory.
  206. """
  207. self._wrappedFactory.doStart()
  208. def doStop(self):
  209. """
  210. Stop notifications are passed straight through to the wrapped factory.
  211. """
  212. self._wrappedFactory.doStop()
  213. def buildProtocol(self, addr):
  214. """
  215. Proxy C{buildProtocol} to our C{self._wrappedFactory} or errback the
  216. C{self._onConnection} L{Deferred} if the wrapped factory raises an
  217. exception or returns L{None}.
  218. @return: An instance of L{_WrappingProtocol} or L{None}
  219. """
  220. try:
  221. proto = self._wrappedFactory.buildProtocol(addr)
  222. if proto is None:
  223. raise error.NoProtocol()
  224. except BaseException:
  225. self._onConnection.errback()
  226. else:
  227. return self.protocol(self._onConnection, proto)
  228. def clientConnectionFailed(self, connector, reason):
  229. """
  230. Errback the C{self._onConnection} L{Deferred} when the
  231. client connection fails.
  232. """
  233. if not self._onConnection.called:
  234. self._onConnection.errback(reason)
  235. @implementer(interfaces.IStreamServerEndpoint)
  236. class StandardIOEndpoint:
  237. """
  238. A Standard Input/Output endpoint
  239. @ivar _stdio: a callable, like L{stdio.StandardIO}, which takes an
  240. L{IProtocol} provider and a C{reactor} keyword argument (interface
  241. dependent upon your platform).
  242. """
  243. _stdio = StandardIO
  244. def __init__(self, reactor):
  245. """
  246. @param reactor: The reactor for the endpoint.
  247. """
  248. self._reactor = reactor
  249. def listen(self, stdioProtocolFactory):
  250. """
  251. Implement L{IStreamServerEndpoint.listen} to listen on stdin/stdout
  252. """
  253. return defer.execute(
  254. self._stdio,
  255. stdioProtocolFactory.buildProtocol(PipeAddress()),
  256. reactor=self._reactor,
  257. )
  258. class _IProcessTransportWithConsumerAndProducer(
  259. interfaces.IProcessTransport, interfaces.IConsumer, interfaces.IPushProducer
  260. ):
  261. """
  262. An L{_IProcessTransportWithConsumerAndProducer} combines various interfaces
  263. to work around the issue that L{interfaces.IProcessTransport} is
  264. incompletely defined and doesn't specify flow-control interfaces, and that
  265. L{proxyForInterface} doesn't allow for multiple interfaces.
  266. """
  267. class _ProcessEndpointTransport(
  268. proxyForInterface( # type: ignore[misc]
  269. _IProcessTransportWithConsumerAndProducer,
  270. "_process",
  271. )
  272. ):
  273. """
  274. An L{ITransport}, L{IProcessTransport}, L{IConsumer}, and L{IPushProducer}
  275. provider for the L{IProtocol} instance passed to the process endpoint.
  276. @ivar _process: An active process transport which will be used by write
  277. methods on this object to write data to a child process.
  278. @type _process: L{interfaces.IProcessTransport} provider
  279. """
  280. class _WrapIProtocol(ProcessProtocol):
  281. """
  282. An L{IProcessProtocol} provider that wraps an L{IProtocol}.
  283. @ivar transport: A L{_ProcessEndpointTransport} provider that is hooked to
  284. the wrapped L{IProtocol} provider.
  285. @see: L{protocol.ProcessProtocol}
  286. """
  287. def __init__(self, proto, executable, errFlag):
  288. """
  289. @param proto: An L{IProtocol} provider.
  290. @param errFlag: A constant belonging to L{StandardErrorBehavior}
  291. that determines if stderr is logged or dropped.
  292. @param executable: The file name (full path) to spawn.
  293. """
  294. self.protocol = proto
  295. self.errFlag = errFlag
  296. self.executable = executable
  297. def makeConnection(self, process):
  298. """
  299. Call L{IProtocol} provider's makeConnection method with an
  300. L{ITransport} provider.
  301. @param process: An L{IProcessTransport} provider.
  302. """
  303. self.transport = _ProcessEndpointTransport(process)
  304. return self.protocol.makeConnection(self.transport)
  305. def childDataReceived(self, childFD, data):
  306. """
  307. This is called with data from the process's stdout or stderr pipes. It
  308. checks the status of the errFlag to setermine if stderr should be
  309. logged (default) or dropped.
  310. """
  311. if childFD == 1:
  312. return self.protocol.dataReceived(data)
  313. elif childFD == 2 and self.errFlag == StandardErrorBehavior.LOG:
  314. log.msg(
  315. format="Process %(executable)r wrote stderr unhandled by "
  316. "%(protocol)s: %(data)s",
  317. executable=self.executable,
  318. protocol=self.protocol,
  319. data=data,
  320. )
  321. def processEnded(self, reason):
  322. """
  323. If the process ends with L{error.ProcessDone}, this method calls the
  324. L{IProtocol} provider's L{connectionLost} with a
  325. L{error.ConnectionDone}
  326. @see: L{ProcessProtocol.processEnded}
  327. """
  328. if (reason.check(error.ProcessDone) == error.ProcessDone) and (
  329. reason.value.status == 0
  330. ):
  331. return self.protocol.connectionLost(Failure(error.ConnectionDone()))
  332. else:
  333. return self.protocol.connectionLost(reason)
  334. class StandardErrorBehavior(Names):
  335. """
  336. Constants used in ProcessEndpoint to decide what to do with stderr.
  337. @cvar LOG: Indicates that stderr is to be logged.
  338. @cvar DROP: Indicates that stderr is to be dropped (and not logged).
  339. @since: 13.1
  340. """
  341. LOG = NamedConstant()
  342. DROP = NamedConstant()
  343. @implementer(interfaces.IStreamClientEndpoint)
  344. class ProcessEndpoint:
  345. """
  346. An endpoint for child processes
  347. @ivar _spawnProcess: A hook used for testing the spawning of child process.
  348. @since: 13.1
  349. """
  350. def __init__(
  351. self,
  352. reactor,
  353. executable,
  354. args=(),
  355. env={},
  356. path=None,
  357. uid=None,
  358. gid=None,
  359. usePTY=0,
  360. childFDs=None,
  361. errFlag=StandardErrorBehavior.LOG,
  362. ):
  363. """
  364. See L{IReactorProcess.spawnProcess}.
  365. @param errFlag: Determines if stderr should be logged.
  366. @type errFlag: L{endpoints.StandardErrorBehavior}
  367. """
  368. self._reactor = reactor
  369. self._executable = executable
  370. self._args = args
  371. self._env = env
  372. self._path = path
  373. self._uid = uid
  374. self._gid = gid
  375. self._usePTY = usePTY
  376. self._childFDs = childFDs
  377. self._errFlag = errFlag
  378. self._spawnProcess = self._reactor.spawnProcess
  379. def connect(self, protocolFactory):
  380. """
  381. Implement L{IStreamClientEndpoint.connect} to launch a child process
  382. and connect it to a protocol created by C{protocolFactory}.
  383. @param protocolFactory: A factory for an L{IProtocol} provider which
  384. will be notified of all events related to the created process.
  385. """
  386. proto = protocolFactory.buildProtocol(_ProcessAddress())
  387. try:
  388. self._spawnProcess(
  389. _WrapIProtocol(proto, self._executable, self._errFlag),
  390. self._executable,
  391. self._args,
  392. self._env,
  393. self._path,
  394. self._uid,
  395. self._gid,
  396. self._usePTY,
  397. self._childFDs,
  398. )
  399. except BaseException:
  400. return defer.fail()
  401. else:
  402. return defer.succeed(proto)
  403. @implementer(interfaces.IStreamServerEndpoint)
  404. class _TCPServerEndpoint:
  405. """
  406. A TCP server endpoint interface
  407. """
  408. def __init__(self, reactor, port, backlog, interface):
  409. """
  410. @param reactor: An L{IReactorTCP} provider.
  411. @param port: The port number used for listening
  412. @type port: int
  413. @param backlog: Size of the listen queue
  414. @type backlog: int
  415. @param interface: The hostname to bind to
  416. @type interface: str
  417. """
  418. self._reactor = reactor
  419. self._port = port
  420. self._backlog = backlog
  421. self._interface = interface
  422. def listen(self, protocolFactory):
  423. """
  424. Implement L{IStreamServerEndpoint.listen} to listen on a TCP
  425. socket
  426. """
  427. return defer.execute(
  428. self._reactor.listenTCP,
  429. self._port,
  430. protocolFactory,
  431. backlog=self._backlog,
  432. interface=self._interface,
  433. )
  434. class TCP4ServerEndpoint(_TCPServerEndpoint):
  435. """
  436. Implements TCP server endpoint with an IPv4 configuration
  437. """
  438. def __init__(self, reactor, port, backlog=50, interface=""):
  439. """
  440. @param reactor: An L{IReactorTCP} provider.
  441. @param port: The port number used for listening
  442. @type port: int
  443. @param backlog: Size of the listen queue
  444. @type backlog: int
  445. @param interface: The hostname to bind to, defaults to '' (all)
  446. @type interface: str
  447. """
  448. _TCPServerEndpoint.__init__(self, reactor, port, backlog, interface)
  449. class TCP6ServerEndpoint(_TCPServerEndpoint):
  450. """
  451. Implements TCP server endpoint with an IPv6 configuration
  452. """
  453. def __init__(self, reactor, port, backlog=50, interface="::"):
  454. """
  455. @param reactor: An L{IReactorTCP} provider.
  456. @param port: The port number used for listening
  457. @type port: int
  458. @param backlog: Size of the listen queue
  459. @type backlog: int
  460. @param interface: The hostname to bind to, defaults to C{::} (all)
  461. @type interface: str
  462. """
  463. _TCPServerEndpoint.__init__(self, reactor, port, backlog, interface)
  464. @implementer(interfaces.IStreamClientEndpoint)
  465. class TCP4ClientEndpoint:
  466. """
  467. TCP client endpoint with an IPv4 configuration.
  468. """
  469. def __init__(self, reactor, host, port, timeout=30, bindAddress=None):
  470. """
  471. @param reactor: An L{IReactorTCP} provider
  472. @param host: A hostname, used when connecting
  473. @type host: str
  474. @param port: The port number, used when connecting
  475. @type port: int
  476. @param timeout: The number of seconds to wait before assuming the
  477. connection has failed.
  478. @type timeout: L{float} or L{int}
  479. @param bindAddress: A (host, port) tuple of local address to bind to,
  480. or None.
  481. @type bindAddress: tuple
  482. """
  483. self._reactor = reactor
  484. self._host = host
  485. self._port = port
  486. self._timeout = timeout
  487. self._bindAddress = bindAddress
  488. def connect(self, protocolFactory):
  489. """
  490. Implement L{IStreamClientEndpoint.connect} to connect via TCP.
  491. """
  492. try:
  493. wf = _WrappingFactory(protocolFactory)
  494. self._reactor.connectTCP(
  495. self._host,
  496. self._port,
  497. wf,
  498. timeout=self._timeout,
  499. bindAddress=self._bindAddress,
  500. )
  501. return wf._onConnection
  502. except BaseException:
  503. return defer.fail()
  504. @implementer(interfaces.IStreamClientEndpoint)
  505. class TCP6ClientEndpoint:
  506. """
  507. TCP client endpoint with an IPv6 configuration.
  508. @ivar _getaddrinfo: A hook used for testing name resolution.
  509. @ivar _deferToThread: A hook used for testing deferToThread.
  510. @ivar _GAI_ADDRESS: Index of the address portion in result of
  511. getaddrinfo to be used.
  512. @ivar _GAI_ADDRESS_HOST: Index of the actual host-address in the
  513. 5-tuple L{_GAI_ADDRESS}.
  514. """
  515. _getaddrinfo = staticmethod(socket.getaddrinfo)
  516. _deferToThread = staticmethod(threads.deferToThread)
  517. _GAI_ADDRESS = 4
  518. _GAI_ADDRESS_HOST = 0
  519. def __init__(self, reactor, host, port, timeout=30, bindAddress=None):
  520. """
  521. @param host: An IPv6 address literal or a hostname with an
  522. IPv6 address
  523. @see: L{twisted.internet.interfaces.IReactorTCP.connectTCP}
  524. """
  525. self._reactor = reactor
  526. self._host = host
  527. self._port = port
  528. self._timeout = timeout
  529. self._bindAddress = bindAddress
  530. def connect(self, protocolFactory):
  531. """
  532. Implement L{IStreamClientEndpoint.connect} to connect via TCP,
  533. once the hostname resolution is done.
  534. """
  535. if isIPv6Address(self._host):
  536. d = self._resolvedHostConnect(self._host, protocolFactory)
  537. else:
  538. d = self._nameResolution(self._host)
  539. d.addCallback(
  540. lambda result: result[0][self._GAI_ADDRESS][self._GAI_ADDRESS_HOST]
  541. )
  542. d.addCallback(self._resolvedHostConnect, protocolFactory)
  543. return d
  544. def _nameResolution(self, host):
  545. """
  546. Resolve the hostname string into a tuple containing the host
  547. IPv6 address.
  548. """
  549. return self._deferToThread(self._getaddrinfo, host, 0, socket.AF_INET6)
  550. def _resolvedHostConnect(self, resolvedHost, protocolFactory):
  551. """
  552. Connect to the server using the resolved hostname.
  553. """
  554. try:
  555. wf = _WrappingFactory(protocolFactory)
  556. self._reactor.connectTCP(
  557. resolvedHost,
  558. self._port,
  559. wf,
  560. timeout=self._timeout,
  561. bindAddress=self._bindAddress,
  562. )
  563. return wf._onConnection
  564. except BaseException:
  565. return defer.fail()
  566. @implementer(IHostnameResolver)
  567. class _SimpleHostnameResolver:
  568. """
  569. An L{IHostnameResolver} provider that invokes a provided callable
  570. to resolve hostnames.
  571. @ivar _nameResolution: the callable L{resolveHostName} invokes to
  572. resolve hostnames.
  573. @type _nameResolution: A L{callable} that accepts two arguments:
  574. the host to resolve and the port number to include in the
  575. result.
  576. """
  577. _log = Logger()
  578. def __init__(self, nameResolution):
  579. """
  580. Create a L{_SimpleHostnameResolver} instance.
  581. """
  582. self._nameResolution = nameResolution
  583. def resolveHostName(
  584. self,
  585. resolutionReceiver,
  586. hostName,
  587. portNumber=0,
  588. addressTypes=None,
  589. transportSemantics="TCP",
  590. ):
  591. """
  592. Initiate a hostname resolution.
  593. @param resolutionReceiver: an object that will receive each resolved
  594. address as it arrives.
  595. @type resolutionReceiver: L{IResolutionReceiver}
  596. @param hostName: see interface
  597. @param portNumber: see interface
  598. @param addressTypes: Ignored in this implementation.
  599. @param transportSemantics: Ignored in this implementation.
  600. @return: The resolution in progress.
  601. @rtype: L{IResolutionReceiver}
  602. """
  603. resolutionReceiver.resolutionBegan(HostResolution(hostName))
  604. d = self._nameResolution(hostName, portNumber)
  605. def cbDeliver(gairesult):
  606. for family, socktype, proto, canonname, sockaddr in gairesult:
  607. if family == socket.AF_INET6:
  608. resolutionReceiver.addressResolved(IPv6Address("TCP", *sockaddr))
  609. elif family == socket.AF_INET:
  610. resolutionReceiver.addressResolved(IPv4Address("TCP", *sockaddr))
  611. def ebLog(error):
  612. self._log.failure(
  613. "while looking up {name} with {callable}",
  614. error,
  615. name=hostName,
  616. callable=self._nameResolution,
  617. )
  618. d.addCallback(cbDeliver)
  619. d.addErrback(ebLog)
  620. d.addBoth(lambda ignored: resolutionReceiver.resolutionComplete())
  621. return resolutionReceiver
  622. @implementer(interfaces.IStreamClientEndpoint)
  623. class HostnameEndpoint:
  624. """
  625. A name-based endpoint that connects to the fastest amongst the resolved
  626. host addresses.
  627. @cvar _DEFAULT_ATTEMPT_DELAY: The default time to use between attempts, in
  628. seconds, when no C{attemptDelay} is given to
  629. L{HostnameEndpoint.__init__}.
  630. @ivar _hostText: the textual representation of the hostname passed to the
  631. constructor. Used to pass to the reactor's hostname resolver.
  632. @type _hostText: L{unicode}
  633. @ivar _hostBytes: the encoded bytes-representation of the hostname passed
  634. to the constructor. Used to construct the L{HostnameAddress}
  635. associated with this endpoint.
  636. @type _hostBytes: L{bytes}
  637. @ivar _hostStr: the native-string representation of the hostname passed to
  638. the constructor, used for exception construction
  639. @type _hostStr: native L{str}
  640. @ivar _badHostname: a flag - hopefully false! - indicating that an invalid
  641. hostname was passed to the constructor. This might be a textual
  642. hostname that isn't valid IDNA, or non-ASCII bytes.
  643. @type _badHostname: L{bool}
  644. """
  645. _getaddrinfo = staticmethod(socket.getaddrinfo)
  646. _deferToThread = staticmethod(threads.deferToThread)
  647. _DEFAULT_ATTEMPT_DELAY = 0.3
  648. def __init__(
  649. self, reactor, host, port, timeout=30, bindAddress=None, attemptDelay=None
  650. ):
  651. """
  652. Create a L{HostnameEndpoint}.
  653. @param reactor: The reactor to use for connections and delayed calls.
  654. @type reactor: provider of L{IReactorTCP}, L{IReactorTime} and either
  655. L{IReactorPluggableNameResolver} or L{IReactorPluggableResolver}.
  656. @param host: A hostname to connect to.
  657. @type host: L{bytes} or L{unicode}
  658. @param port: The port number to connect to.
  659. @type port: L{int}
  660. @param timeout: For each individual connection attempt, the number of
  661. seconds to wait before assuming the connection has failed.
  662. @type timeout: L{float} or L{int}
  663. @param bindAddress: the local address of the network interface to make
  664. the connections from.
  665. @type bindAddress: L{bytes}
  666. @param attemptDelay: The number of seconds to delay between connection
  667. attempts.
  668. @type attemptDelay: L{float}
  669. @see: L{twisted.internet.interfaces.IReactorTCP.connectTCP}
  670. """
  671. self._reactor = reactor
  672. self._nameResolver = self._getNameResolverAndMaybeWarn(reactor)
  673. [self._badHostname, self._hostBytes, self._hostText] = self._hostAsBytesAndText(
  674. host
  675. )
  676. self._hostStr = self._hostBytes if bytes is str else self._hostText
  677. self._port = port
  678. self._timeout = timeout
  679. self._bindAddress = bindAddress
  680. if attemptDelay is None:
  681. attemptDelay = self._DEFAULT_ATTEMPT_DELAY
  682. self._attemptDelay = attemptDelay
  683. def __repr__(self) -> str:
  684. """
  685. Produce a string representation of the L{HostnameEndpoint}.
  686. @return: A L{str}
  687. """
  688. if self._badHostname:
  689. # Use the backslash-encoded version of the string passed to the
  690. # constructor, which is already a native string.
  691. host = self._hostStr
  692. elif isIPv6Address(self._hostStr):
  693. host = f"[{self._hostStr}]"
  694. else:
  695. # Convert the bytes representation to a native string to ensure
  696. # that we display the punycoded version of the hostname, which is
  697. # more useful than any IDN version as it can be easily copy-pasted
  698. # into debugging tools.
  699. host = nativeString(self._hostBytes)
  700. return "".join(["<HostnameEndpoint ", host, ":", str(self._port), ">"])
  701. def _getNameResolverAndMaybeWarn(self, reactor):
  702. """
  703. Retrieve a C{nameResolver} callable and warn the caller's
  704. caller that using a reactor which doesn't provide
  705. L{IReactorPluggableNameResolver} is deprecated.
  706. @param reactor: The reactor to check.
  707. @return: A L{IHostnameResolver} provider.
  708. """
  709. if not IReactorPluggableNameResolver.providedBy(reactor):
  710. warningString = deprecate.getDeprecationWarningString(
  711. reactor.__class__,
  712. Version("Twisted", 17, 5, 0),
  713. format=(
  714. "Passing HostnameEndpoint a reactor that does not"
  715. " provide IReactorPluggableNameResolver (%(fqpn)s)"
  716. " was deprecated in %(version)s"
  717. ),
  718. replacement=(
  719. "a reactor that provides" " IReactorPluggableNameResolver"
  720. ),
  721. )
  722. warnings.warn(warningString, DeprecationWarning, stacklevel=3)
  723. return _SimpleHostnameResolver(self._fallbackNameResolution)
  724. return reactor.nameResolver
  725. @staticmethod
  726. def _hostAsBytesAndText(host):
  727. """
  728. For various reasons (documented in the C{@ivar}'s in the class
  729. docstring) we need both a textual and a binary representation of the
  730. hostname given to the constructor. For compatibility and convenience,
  731. we accept both textual and binary representations of the hostname, save
  732. the form that was passed, and convert into the other form. This is
  733. mostly just because L{HostnameAddress} chose somewhat poorly to define
  734. its attribute as bytes; hopefully we can find a compatible way to clean
  735. this up in the future and just operate in terms of text internally.
  736. @param host: A hostname to convert.
  737. @type host: L{bytes} or C{str}
  738. @return: a 3-tuple of C{(invalid, bytes, text)} where C{invalid} is a
  739. boolean indicating the validity of the hostname, C{bytes} is a
  740. binary representation of C{host}, and C{text} is a textual
  741. representation of C{host}.
  742. """
  743. if isinstance(host, bytes):
  744. if isIPAddress(host) or isIPv6Address(host):
  745. return False, host, host.decode("ascii")
  746. else:
  747. try:
  748. return False, host, _idnaText(host)
  749. except UnicodeError:
  750. # Convert the host to _some_ kind of text, to handle below.
  751. host = host.decode("charmap")
  752. else:
  753. host = normalize("NFC", host)
  754. if isIPAddress(host) or isIPv6Address(host):
  755. return False, host.encode("ascii"), host
  756. else:
  757. try:
  758. return False, _idnaBytes(host), host
  759. except UnicodeError:
  760. pass
  761. # `host` has been converted to text by this point either way; it's
  762. # invalid as a hostname, and so may contain unprintable characters and
  763. # such. escape it with backslashes so the user can get _some_ guess as
  764. # to what went wrong.
  765. asciibytes = host.encode("ascii", "backslashreplace")
  766. return True, asciibytes, asciibytes.decode("ascii")
  767. def connect(self, protocolFactory):
  768. """
  769. Attempts a connection to each resolved address, and returns a
  770. connection which is established first.
  771. @param protocolFactory: The protocol factory whose protocol
  772. will be connected.
  773. @type protocolFactory:
  774. L{IProtocolFactory<twisted.internet.interfaces.IProtocolFactory>}
  775. @return: A L{Deferred} that fires with the connected protocol
  776. or fails a connection-related error.
  777. """
  778. if self._badHostname:
  779. return defer.fail(ValueError(f"invalid hostname: {self._hostStr}"))
  780. d = Deferred()
  781. addresses = []
  782. @provider(IResolutionReceiver)
  783. class EndpointReceiver:
  784. @staticmethod
  785. def resolutionBegan(resolutionInProgress):
  786. pass
  787. @staticmethod
  788. def addressResolved(address):
  789. addresses.append(address)
  790. @staticmethod
  791. def resolutionComplete():
  792. d.callback(addresses)
  793. self._nameResolver.resolveHostName(
  794. EndpointReceiver, self._hostText, portNumber=self._port
  795. )
  796. d.addErrback(
  797. lambda ignored: defer.fail(
  798. error.DNSLookupError(f"Couldn't find the hostname '{self._hostStr}'")
  799. )
  800. )
  801. @d.addCallback
  802. def resolvedAddressesToEndpoints(addresses):
  803. # Yield an endpoint for every address resolved from the name.
  804. for eachAddress in addresses:
  805. if isinstance(eachAddress, IPv6Address):
  806. yield TCP6ClientEndpoint(
  807. self._reactor,
  808. eachAddress.host,
  809. eachAddress.port,
  810. self._timeout,
  811. self._bindAddress,
  812. )
  813. if isinstance(eachAddress, IPv4Address):
  814. yield TCP4ClientEndpoint(
  815. self._reactor,
  816. eachAddress.host,
  817. eachAddress.port,
  818. self._timeout,
  819. self._bindAddress,
  820. )
  821. d.addCallback(list)
  822. def _canceller(d):
  823. # This canceller must remain defined outside of
  824. # `startConnectionAttempts`, because Deferred should not
  825. # participate in cycles with their cancellers; that would create a
  826. # potentially problematic circular reference and possibly
  827. # gc.garbage.
  828. d.errback(
  829. error.ConnectingCancelledError(
  830. HostnameAddress(self._hostBytes, self._port)
  831. )
  832. )
  833. @d.addCallback
  834. def startConnectionAttempts(endpoints):
  835. """
  836. Given a sequence of endpoints obtained via name resolution, start
  837. connecting to a new one every C{self._attemptDelay} seconds until
  838. one of the connections succeeds, all of them fail, or the attempt
  839. is cancelled.
  840. @param endpoints: a list of all the endpoints we might try to
  841. connect to, as determined by name resolution.
  842. @type endpoints: L{list} of L{IStreamServerEndpoint}
  843. @return: a Deferred that fires with the result of the
  844. C{endpoint.connect} method that completes the fastest, or fails
  845. with the first connection error it encountered if none of them
  846. succeed.
  847. @rtype: L{Deferred} failing with L{error.ConnectingCancelledError}
  848. or firing with L{IProtocol}
  849. """
  850. if not endpoints:
  851. raise error.DNSLookupError(
  852. f"no results for hostname lookup: {self._hostStr}"
  853. )
  854. iterEndpoints = iter(endpoints)
  855. pending = []
  856. failures = []
  857. winner = defer.Deferred(canceller=_canceller)
  858. def checkDone():
  859. if pending or checkDone.completed or checkDone.endpointsLeft:
  860. return
  861. winner.errback(failures.pop())
  862. checkDone.completed = False
  863. checkDone.endpointsLeft = True
  864. @LoopingCall
  865. def iterateEndpoint():
  866. endpoint = next(iterEndpoints, None)
  867. if endpoint is None:
  868. # The list of endpoints ends.
  869. checkDone.endpointsLeft = False
  870. checkDone()
  871. return
  872. eachAttempt = endpoint.connect(protocolFactory)
  873. pending.append(eachAttempt)
  874. @eachAttempt.addBoth
  875. def noLongerPending(result):
  876. pending.remove(eachAttempt)
  877. return result
  878. @eachAttempt.addCallback
  879. def succeeded(result):
  880. winner.callback(result)
  881. @eachAttempt.addErrback
  882. def failed(reason):
  883. failures.append(reason)
  884. checkDone()
  885. iterateEndpoint.clock = self._reactor
  886. iterateEndpoint.start(self._attemptDelay)
  887. @winner.addBoth
  888. def cancelRemainingPending(result):
  889. checkDone.completed = True
  890. for remaining in pending[:]:
  891. remaining.cancel()
  892. if iterateEndpoint.running:
  893. iterateEndpoint.stop()
  894. return result
  895. return winner
  896. return d
  897. def _fallbackNameResolution(self, host, port):
  898. """
  899. Resolve the hostname string into a tuple containing the host
  900. address. This is method is only used when the reactor does
  901. not provide L{IReactorPluggableNameResolver}.
  902. @param host: A unicode hostname to resolve.
  903. @param port: The port to include in the resolution.
  904. @return: A L{Deferred} that fires with L{_getaddrinfo}'s
  905. return value.
  906. """
  907. return self._deferToThread(self._getaddrinfo, host, port, 0, socket.SOCK_STREAM)
  908. @implementer(interfaces.IStreamServerEndpoint)
  909. class SSL4ServerEndpoint:
  910. """
  911. SSL secured TCP server endpoint with an IPv4 configuration.
  912. """
  913. def __init__(self, reactor, port, sslContextFactory, backlog=50, interface=""):
  914. """
  915. @param reactor: An L{IReactorSSL} provider.
  916. @param port: The port number used for listening
  917. @type port: int
  918. @param sslContextFactory: An instance of
  919. L{interfaces.IOpenSSLContextFactory}.
  920. @param backlog: Size of the listen queue
  921. @type backlog: int
  922. @param interface: The hostname to bind to, defaults to '' (all)
  923. @type interface: str
  924. """
  925. self._reactor = reactor
  926. self._port = port
  927. self._sslContextFactory = sslContextFactory
  928. self._backlog = backlog
  929. self._interface = interface
  930. def listen(self, protocolFactory):
  931. """
  932. Implement L{IStreamServerEndpoint.listen} to listen for SSL on a
  933. TCP socket.
  934. """
  935. return defer.execute(
  936. self._reactor.listenSSL,
  937. self._port,
  938. protocolFactory,
  939. contextFactory=self._sslContextFactory,
  940. backlog=self._backlog,
  941. interface=self._interface,
  942. )
  943. @implementer(interfaces.IStreamClientEndpoint)
  944. class SSL4ClientEndpoint:
  945. """
  946. SSL secured TCP client endpoint with an IPv4 configuration
  947. """
  948. def __init__(
  949. self, reactor, host, port, sslContextFactory, timeout=30, bindAddress=None
  950. ):
  951. """
  952. @param reactor: An L{IReactorSSL} provider.
  953. @param host: A hostname, used when connecting
  954. @type host: str
  955. @param port: The port number, used when connecting
  956. @type port: int
  957. @param sslContextFactory: SSL Configuration information as an instance
  958. of L{interfaces.IOpenSSLContextFactory}.
  959. @param timeout: Number of seconds to wait before assuming the
  960. connection has failed.
  961. @type timeout: int
  962. @param bindAddress: A (host, port) tuple of local address to bind to,
  963. or None.
  964. @type bindAddress: tuple
  965. """
  966. self._reactor = reactor
  967. self._host = host
  968. self._port = port
  969. self._sslContextFactory = sslContextFactory
  970. self._timeout = timeout
  971. self._bindAddress = bindAddress
  972. def connect(self, protocolFactory):
  973. """
  974. Implement L{IStreamClientEndpoint.connect} to connect with SSL over
  975. TCP.
  976. """
  977. try:
  978. wf = _WrappingFactory(protocolFactory)
  979. self._reactor.connectSSL(
  980. self._host,
  981. self._port,
  982. wf,
  983. self._sslContextFactory,
  984. timeout=self._timeout,
  985. bindAddress=self._bindAddress,
  986. )
  987. return wf._onConnection
  988. except BaseException:
  989. return defer.fail()
  990. @implementer(interfaces.IStreamServerEndpoint)
  991. class UNIXServerEndpoint:
  992. """
  993. UnixSocket server endpoint.
  994. """
  995. def __init__(self, reactor, address, backlog=50, mode=0o666, wantPID=0):
  996. """
  997. @param reactor: An L{IReactorUNIX} provider.
  998. @param address: The path to the Unix socket file, used when listening
  999. @param backlog: number of connections to allow in backlog.
  1000. @param mode: mode to set on the unix socket. This parameter is
  1001. deprecated. Permissions should be set on the directory which
  1002. contains the UNIX socket.
  1003. @param wantPID: If True, create a pidfile for the socket.
  1004. """
  1005. self._reactor = reactor
  1006. self._address = address
  1007. self._backlog = backlog
  1008. self._mode = mode
  1009. self._wantPID = wantPID
  1010. def listen(self, protocolFactory):
  1011. """
  1012. Implement L{IStreamServerEndpoint.listen} to listen on a UNIX socket.
  1013. """
  1014. return defer.execute(
  1015. self._reactor.listenUNIX,
  1016. self._address,
  1017. protocolFactory,
  1018. backlog=self._backlog,
  1019. mode=self._mode,
  1020. wantPID=self._wantPID,
  1021. )
  1022. @implementer(interfaces.IStreamClientEndpoint)
  1023. class UNIXClientEndpoint:
  1024. """
  1025. UnixSocket client endpoint.
  1026. """
  1027. def __init__(self, reactor, path, timeout=30, checkPID=0):
  1028. """
  1029. @param reactor: An L{IReactorUNIX} provider.
  1030. @param path: The path to the Unix socket file, used when connecting
  1031. @type path: str
  1032. @param timeout: Number of seconds to wait before assuming the
  1033. connection has failed.
  1034. @type timeout: int
  1035. @param checkPID: If True, check for a pid file to verify that a server
  1036. is listening.
  1037. @type checkPID: bool
  1038. """
  1039. self._reactor = reactor
  1040. self._path = path
  1041. self._timeout = timeout
  1042. self._checkPID = checkPID
  1043. def connect(self, protocolFactory):
  1044. """
  1045. Implement L{IStreamClientEndpoint.connect} to connect via a
  1046. UNIX Socket
  1047. """
  1048. try:
  1049. wf = _WrappingFactory(protocolFactory)
  1050. self._reactor.connectUNIX(
  1051. self._path, wf, timeout=self._timeout, checkPID=self._checkPID
  1052. )
  1053. return wf._onConnection
  1054. except BaseException:
  1055. return defer.fail()
  1056. @implementer(interfaces.IStreamServerEndpoint)
  1057. class AdoptedStreamServerEndpoint:
  1058. """
  1059. An endpoint for listening on a file descriptor initialized outside of
  1060. Twisted.
  1061. @ivar _used: A C{bool} indicating whether this endpoint has been used to
  1062. listen with a factory yet. C{True} if so.
  1063. """
  1064. _close = os.close
  1065. _setNonBlocking = staticmethod(fdesc.setNonBlocking)
  1066. def __init__(self, reactor, fileno, addressFamily):
  1067. """
  1068. @param reactor: An L{IReactorSocket} provider.
  1069. @param fileno: An integer file descriptor corresponding to a listening
  1070. I{SOCK_STREAM} socket.
  1071. @param addressFamily: The address family of the socket given by
  1072. C{fileno}.
  1073. """
  1074. self.reactor = reactor
  1075. self.fileno = fileno
  1076. self.addressFamily = addressFamily
  1077. self._used = False
  1078. def listen(self, factory):
  1079. """
  1080. Implement L{IStreamServerEndpoint.listen} to start listening on, and
  1081. then close, C{self._fileno}.
  1082. """
  1083. if self._used:
  1084. return defer.fail(error.AlreadyListened())
  1085. self._used = True
  1086. try:
  1087. self._setNonBlocking(self.fileno)
  1088. port = self.reactor.adoptStreamPort(
  1089. self.fileno, self.addressFamily, factory
  1090. )
  1091. self._close(self.fileno)
  1092. except BaseException:
  1093. return defer.fail()
  1094. return defer.succeed(port)
  1095. def _parseTCP(factory, port, interface="", backlog=50):
  1096. """
  1097. Internal parser function for L{_parseServer} to convert the string
  1098. arguments for a TCP(IPv4) stream endpoint into the structured arguments.
  1099. @param factory: the protocol factory being parsed, or L{None}. (This was a
  1100. leftover argument from when this code was in C{strports}, and is now
  1101. mostly None and unused.)
  1102. @type factory: L{IProtocolFactory} or L{None}
  1103. @param port: the integer port number to bind
  1104. @type port: C{str}
  1105. @param interface: the interface IP to listen on
  1106. @param backlog: the length of the listen queue
  1107. @type backlog: C{str}
  1108. @return: a 2-tuple of (args, kwargs), describing the parameters to
  1109. L{IReactorTCP.listenTCP} (or, modulo argument 2, the factory, arguments
  1110. to L{TCP4ServerEndpoint}.
  1111. """
  1112. return (int(port), factory), {"interface": interface, "backlog": int(backlog)}
  1113. def _parseUNIX(factory, address, mode="666", backlog=50, lockfile=True):
  1114. """
  1115. Internal parser function for L{_parseServer} to convert the string
  1116. arguments for a UNIX (AF_UNIX/SOCK_STREAM) stream endpoint into the
  1117. structured arguments.
  1118. @param factory: the protocol factory being parsed, or L{None}. (This was a
  1119. leftover argument from when this code was in C{strports}, and is now
  1120. mostly None and unused.)
  1121. @type factory: L{IProtocolFactory} or L{None}
  1122. @param address: the pathname of the unix socket
  1123. @type address: C{str}
  1124. @param backlog: the length of the listen queue
  1125. @type backlog: C{str}
  1126. @param lockfile: A string '0' or '1', mapping to True and False
  1127. respectively. See the C{wantPID} argument to C{listenUNIX}
  1128. @return: a 2-tuple of (args, kwargs), describing the parameters to
  1129. L{twisted.internet.interfaces.IReactorUNIX.listenUNIX} (or,
  1130. modulo argument 2, the factory, arguments to L{UNIXServerEndpoint}.
  1131. """
  1132. return (
  1133. (address, factory),
  1134. {"mode": int(mode, 8), "backlog": int(backlog), "wantPID": bool(int(lockfile))},
  1135. )
  1136. def _parseSSL(
  1137. factory,
  1138. port,
  1139. privateKey="server.pem",
  1140. certKey=None,
  1141. sslmethod=None,
  1142. interface="",
  1143. backlog=50,
  1144. extraCertChain=None,
  1145. dhParameters=None,
  1146. ):
  1147. """
  1148. Internal parser function for L{_parseServer} to convert the string
  1149. arguments for an SSL (over TCP/IPv4) stream endpoint into the structured
  1150. arguments.
  1151. @param factory: the protocol factory being parsed, or L{None}. (This was a
  1152. leftover argument from when this code was in C{strports}, and is now
  1153. mostly None and unused.)
  1154. @type factory: L{IProtocolFactory} or L{None}
  1155. @param port: the integer port number to bind
  1156. @type port: C{str}
  1157. @param interface: the interface IP to listen on
  1158. @param backlog: the length of the listen queue
  1159. @type backlog: C{str}
  1160. @param privateKey: The file name of a PEM format private key file.
  1161. @type privateKey: C{str}
  1162. @param certKey: The file name of a PEM format certificate file.
  1163. @type certKey: C{str}
  1164. @param sslmethod: The string name of an SSL method, based on the name of a
  1165. constant in C{OpenSSL.SSL}.
  1166. @type sslmethod: C{str}
  1167. @param extraCertChain: The path of a file containing one or more
  1168. certificates in PEM format that establish the chain from a root CA to
  1169. the CA that signed your C{certKey}.
  1170. @type extraCertChain: L{str}
  1171. @param dhParameters: The file name of a file containing parameters that are
  1172. required for Diffie-Hellman key exchange. If this is not specified,
  1173. the forward secret C{DHE} ciphers aren't available for servers.
  1174. @type dhParameters: L{str}
  1175. @return: a 2-tuple of (args, kwargs), describing the parameters to
  1176. L{IReactorSSL.listenSSL} (or, modulo argument 2, the factory, arguments
  1177. to L{SSL4ServerEndpoint}.
  1178. """
  1179. from twisted.internet import ssl
  1180. if certKey is None:
  1181. certKey = privateKey
  1182. kw = {}
  1183. if sslmethod is not None:
  1184. kw["method"] = getattr(ssl.SSL, sslmethod)
  1185. certPEM = FilePath(certKey).getContent()
  1186. keyPEM = FilePath(privateKey).getContent()
  1187. privateCertificate = ssl.PrivateCertificate.loadPEM(certPEM + b"\n" + keyPEM)
  1188. if extraCertChain is not None:
  1189. matches = re.findall(
  1190. r"(-----BEGIN CERTIFICATE-----\n.+?\n-----END CERTIFICATE-----)",
  1191. nativeString(FilePath(extraCertChain).getContent()),
  1192. flags=re.DOTALL,
  1193. )
  1194. chainCertificates = [
  1195. ssl.Certificate.loadPEM(chainCertPEM).original for chainCertPEM in matches
  1196. ]
  1197. if not chainCertificates:
  1198. raise ValueError(
  1199. "Specified chain file '%s' doesn't contain any valid "
  1200. "certificates in PEM format." % (extraCertChain,)
  1201. )
  1202. else:
  1203. chainCertificates = None
  1204. if dhParameters is not None:
  1205. dhParameters = ssl.DiffieHellmanParameters.fromFile(
  1206. FilePath(dhParameters),
  1207. )
  1208. cf = ssl.CertificateOptions(
  1209. privateKey=privateCertificate.privateKey.original,
  1210. certificate=privateCertificate.original,
  1211. extraCertChain=chainCertificates,
  1212. dhParameters=dhParameters,
  1213. **kw,
  1214. )
  1215. return ((int(port), factory, cf), {"interface": interface, "backlog": int(backlog)})
  1216. @implementer(IPlugin, IStreamServerEndpointStringParser)
  1217. class _StandardIOParser:
  1218. """
  1219. Stream server endpoint string parser for the Standard I/O type.
  1220. @ivar prefix: See L{IStreamServerEndpointStringParser.prefix}.
  1221. """
  1222. prefix = "stdio"
  1223. def _parseServer(self, reactor):
  1224. """
  1225. Internal parser function for L{_parseServer} to convert the string
  1226. arguments into structured arguments for the L{StandardIOEndpoint}
  1227. @param reactor: Reactor for the endpoint
  1228. """
  1229. return StandardIOEndpoint(reactor)
  1230. def parseStreamServer(self, reactor, *args, **kwargs):
  1231. # Redirects to another function (self._parseServer), tricks zope.interface
  1232. # into believing the interface is correctly implemented.
  1233. return self._parseServer(reactor)
  1234. @implementer(IPlugin, IStreamServerEndpointStringParser)
  1235. class _SystemdParser:
  1236. """
  1237. Stream server endpoint string parser for the I{systemd} endpoint type.
  1238. @ivar prefix: See L{IStreamServerEndpointStringParser.prefix}.
  1239. @ivar _sddaemon: A L{ListenFDs} instance used to translate an index into an
  1240. actual file descriptor.
  1241. """
  1242. _sddaemon = ListenFDs.fromEnvironment()
  1243. prefix = "systemd"
  1244. def _parseServer(
  1245. self,
  1246. reactor: IReactorSocket,
  1247. domain: str,
  1248. index: Optional[str] = None,
  1249. name: Optional[str] = None,
  1250. ) -> AdoptedStreamServerEndpoint:
  1251. """
  1252. Internal parser function for L{_parseServer} to convert the string
  1253. arguments for a systemd server endpoint into structured arguments for
  1254. L{AdoptedStreamServerEndpoint}.
  1255. @param reactor: An L{IReactorSocket} provider.
  1256. @param domain: The domain (or address family) of the socket inherited
  1257. from systemd. This is a string like C{"INET"} or C{"UNIX"}, ie
  1258. the name of an address family from the L{socket} module, without
  1259. the C{"AF_"} prefix.
  1260. @param index: If given, the decimal representation of an integer
  1261. giving the offset into the list of file descriptors inherited from
  1262. systemd. Since the order of descriptors received from systemd is
  1263. hard to predict, this option should only be used if only one
  1264. descriptor is being inherited. Even in that case, C{name} is
  1265. probably a better idea. Either C{index} or C{name} must be given.
  1266. @param name: If given, the name (as defined by C{FileDescriptorName}
  1267. in the C{[Socket]} section of a systemd service definition) of an
  1268. inherited file descriptor. Either C{index} or C{name} must be
  1269. given.
  1270. @return: An L{AdoptedStreamServerEndpoint} which will adopt the
  1271. inherited listening port when it is used to listen.
  1272. """
  1273. if (index is None) == (name is None):
  1274. raise ValueError("Specify exactly one of descriptor index or name")
  1275. if index is not None:
  1276. fileno = self._sddaemon.inheritedDescriptors()[int(index)]
  1277. else:
  1278. assert name is not None
  1279. fileno = self._sddaemon.inheritedNamedDescriptors()[name]
  1280. addressFamily = getattr(socket, "AF_" + domain)
  1281. return AdoptedStreamServerEndpoint(reactor, fileno, addressFamily)
  1282. def parseStreamServer(self, reactor, *args, **kwargs):
  1283. # Delegate to another function with a sane signature. This function has
  1284. # an insane signature to trick zope.interface into believing the
  1285. # interface is correctly implemented.
  1286. return self._parseServer(reactor, *args, **kwargs)
  1287. @implementer(IPlugin, IStreamServerEndpointStringParser)
  1288. class _TCP6ServerParser:
  1289. """
  1290. Stream server endpoint string parser for the TCP6ServerEndpoint type.
  1291. @ivar prefix: See L{IStreamServerEndpointStringParser.prefix}.
  1292. """
  1293. prefix = (
  1294. "tcp6" # Used in _parseServer to identify the plugin with the endpoint type
  1295. )
  1296. def _parseServer(self, reactor, port, backlog=50, interface="::"):
  1297. """
  1298. Internal parser function for L{_parseServer} to convert the string
  1299. arguments into structured arguments for the L{TCP6ServerEndpoint}
  1300. @param reactor: An L{IReactorTCP} provider.
  1301. @param port: The port number used for listening
  1302. @type port: int
  1303. @param backlog: Size of the listen queue
  1304. @type backlog: int
  1305. @param interface: The hostname to bind to
  1306. @type interface: str
  1307. """
  1308. port = int(port)
  1309. backlog = int(backlog)
  1310. return TCP6ServerEndpoint(reactor, port, backlog, interface)
  1311. def parseStreamServer(self, reactor, *args, **kwargs):
  1312. # Redirects to another function (self._parseServer), tricks zope.interface
  1313. # into believing the interface is correctly implemented.
  1314. return self._parseServer(reactor, *args, **kwargs)
  1315. _serverParsers = {
  1316. "tcp": _parseTCP,
  1317. "unix": _parseUNIX,
  1318. "ssl": _parseSSL,
  1319. }
  1320. _OP, _STRING = range(2)
  1321. def _tokenize(description):
  1322. """
  1323. Tokenize a strports string and yield each token.
  1324. @param description: a string as described by L{serverFromString} or
  1325. L{clientFromString}.
  1326. @type description: L{str} or L{bytes}
  1327. @return: an iterable of 2-tuples of (C{_OP} or C{_STRING}, string). Tuples
  1328. starting with C{_OP} will contain a second element of either ':' (i.e.
  1329. 'next parameter') or '=' (i.e. 'assign parameter value'). For example,
  1330. the string 'hello:greeting=world' would result in a generator yielding
  1331. these values::
  1332. _STRING, 'hello'
  1333. _OP, ':'
  1334. _STRING, 'greet=ing'
  1335. _OP, '='
  1336. _STRING, 'world'
  1337. """
  1338. empty = _matchingString("", description)
  1339. colon = _matchingString(":", description)
  1340. equals = _matchingString("=", description)
  1341. backslash = _matchingString("\x5c", description)
  1342. current = empty
  1343. ops = colon + equals
  1344. nextOps = {colon: colon + equals, equals: colon}
  1345. iterdesc = iter(iterbytes(description))
  1346. for n in iterdesc:
  1347. if n in iterbytes(ops):
  1348. yield _STRING, current
  1349. yield _OP, n
  1350. current = empty
  1351. ops = nextOps[n]
  1352. elif n == backslash:
  1353. current += next(iterdesc)
  1354. else:
  1355. current += n
  1356. yield _STRING, current
  1357. def _parse(description):
  1358. """
  1359. Convert a description string into a list of positional and keyword
  1360. parameters, using logic vaguely like what Python does.
  1361. @param description: a string as described by L{serverFromString} or
  1362. L{clientFromString}.
  1363. @return: a 2-tuple of C{(args, kwargs)}, where 'args' is a list of all
  1364. ':'-separated C{str}s not containing an '=' and 'kwargs' is a map of
  1365. all C{str}s which do contain an '='. For example, the result of
  1366. C{_parse('a:b:d=1:c')} would be C{(['a', 'b', 'c'], {'d': '1'})}.
  1367. """
  1368. args, kw = [], {}
  1369. colon = _matchingString(":", description)
  1370. def add(sofar):
  1371. if len(sofar) == 1:
  1372. args.append(sofar[0])
  1373. else:
  1374. kw[nativeString(sofar[0])] = sofar[1]
  1375. sofar = ()
  1376. for (type, value) in _tokenize(description):
  1377. if type is _STRING:
  1378. sofar += (value,)
  1379. elif value == colon:
  1380. add(sofar)
  1381. sofar = ()
  1382. add(sofar)
  1383. return args, kw
  1384. # Mappings from description "names" to endpoint constructors.
  1385. _endpointServerFactories = {
  1386. "TCP": TCP4ServerEndpoint,
  1387. "SSL": SSL4ServerEndpoint,
  1388. "UNIX": UNIXServerEndpoint,
  1389. }
  1390. _endpointClientFactories = {
  1391. "TCP": TCP4ClientEndpoint,
  1392. "SSL": SSL4ClientEndpoint,
  1393. "UNIX": UNIXClientEndpoint,
  1394. }
  1395. def _parseServer(description, factory):
  1396. """
  1397. Parse a strports description into a 2-tuple of arguments and keyword
  1398. values.
  1399. @param description: A description in the format explained by
  1400. L{serverFromString}.
  1401. @type description: C{str}
  1402. @param factory: A 'factory' argument; this is left-over from
  1403. twisted.application.strports, it's not really used.
  1404. @type factory: L{IProtocolFactory} or L{None}
  1405. @return: a 3-tuple of (plugin or name, arguments, keyword arguments)
  1406. """
  1407. args, kw = _parse(description)
  1408. endpointType = args[0]
  1409. parser = _serverParsers.get(endpointType)
  1410. if parser is None:
  1411. # If the required parser is not found in _server, check if
  1412. # a plugin exists for the endpointType
  1413. plugin = _matchPluginToPrefix(
  1414. getPlugins(IStreamServerEndpointStringParser), endpointType
  1415. )
  1416. return (plugin, args[1:], kw)
  1417. return (endpointType.upper(),) + parser(factory, *args[1:], **kw)
  1418. def _matchPluginToPrefix(plugins, endpointType):
  1419. """
  1420. Match plugin to prefix.
  1421. """
  1422. endpointType = endpointType.lower()
  1423. for plugin in plugins:
  1424. if _matchingString(plugin.prefix.lower(), endpointType) == endpointType:
  1425. return plugin
  1426. raise ValueError(f"Unknown endpoint type: '{endpointType}'")
  1427. def serverFromString(reactor, description):
  1428. """
  1429. Construct a stream server endpoint from an endpoint description string.
  1430. The format for server endpoint descriptions is a simple byte string. It is
  1431. a prefix naming the type of endpoint, then a colon, then the arguments for
  1432. that endpoint.
  1433. For example, you can call it like this to create an endpoint that will
  1434. listen on TCP port 80::
  1435. serverFromString(reactor, "tcp:80")
  1436. Additional arguments may be specified as keywords, separated with colons.
  1437. For example, you can specify the interface for a TCP server endpoint to
  1438. bind to like this::
  1439. serverFromString(reactor, "tcp:80:interface=127.0.0.1")
  1440. SSL server endpoints may be specified with the 'ssl' prefix, and the
  1441. private key and certificate files may be specified by the C{privateKey} and
  1442. C{certKey} arguments::
  1443. serverFromString(
  1444. reactor, "ssl:443:privateKey=key.pem:certKey=crt.pem")
  1445. If a private key file name (C{privateKey}) isn't provided, a "server.pem"
  1446. file is assumed to exist which contains the private key. If the certificate
  1447. file name (C{certKey}) isn't provided, the private key file is assumed to
  1448. contain the certificate as well.
  1449. You may escape colons in arguments with a backslash, which you will need to
  1450. use if you want to specify a full pathname argument on Windows::
  1451. serverFromString(reactor,
  1452. "ssl:443:privateKey=C\\:/key.pem:certKey=C\\:/cert.pem")
  1453. finally, the 'unix' prefix may be used to specify a filesystem UNIX socket,
  1454. optionally with a 'mode' argument to specify the mode of the socket file
  1455. created by C{listen}::
  1456. serverFromString(reactor, "unix:/var/run/finger")
  1457. serverFromString(reactor, "unix:/var/run/finger:mode=660")
  1458. This function is also extensible; new endpoint types may be registered as
  1459. L{IStreamServerEndpointStringParser} plugins. See that interface for more
  1460. information.
  1461. @param reactor: The server endpoint will be constructed with this reactor.
  1462. @param description: The strports description to parse.
  1463. @type description: L{str}
  1464. @return: A new endpoint which can be used to listen with the parameters
  1465. given by C{description}.
  1466. @rtype: L{IStreamServerEndpoint<twisted.internet.interfaces.IStreamServerEndpoint>}
  1467. @raise ValueError: when the 'description' string cannot be parsed.
  1468. @since: 10.2
  1469. """
  1470. nameOrPlugin, args, kw = _parseServer(description, None)
  1471. if type(nameOrPlugin) is not str:
  1472. plugin = nameOrPlugin
  1473. return plugin.parseStreamServer(reactor, *args, **kw)
  1474. else:
  1475. name = nameOrPlugin
  1476. # Chop out the factory.
  1477. args = args[:1] + args[2:]
  1478. return _endpointServerFactories[name](reactor, *args, **kw)
  1479. def quoteStringArgument(argument):
  1480. """
  1481. Quote an argument to L{serverFromString} and L{clientFromString}. Since
  1482. arguments are separated with colons and colons are escaped with
  1483. backslashes, some care is necessary if, for example, you have a pathname,
  1484. you may be tempted to interpolate into a string like this::
  1485. serverFromString(reactor, "ssl:443:privateKey=%s" % (myPathName,))
  1486. This may appear to work, but will have portability issues (Windows
  1487. pathnames, for example). Usually you should just construct the appropriate
  1488. endpoint type rather than interpolating strings, which in this case would
  1489. be L{SSL4ServerEndpoint}. There are some use-cases where you may need to
  1490. generate such a string, though; for example, a tool to manipulate a
  1491. configuration file which has strports descriptions in it. To be correct in
  1492. those cases, do this instead::
  1493. serverFromString(reactor, "ssl:443:privateKey=%s" %
  1494. (quoteStringArgument(myPathName),))
  1495. @param argument: The part of the endpoint description string you want to
  1496. pass through.
  1497. @type argument: C{str}
  1498. @return: The quoted argument.
  1499. @rtype: C{str}
  1500. """
  1501. backslash, colon = "\\:"
  1502. for c in backslash, colon:
  1503. argument = argument.replace(c, backslash + c)
  1504. return argument
  1505. def _parseClientTCP(*args, **kwargs):
  1506. """
  1507. Perform any argument value coercion necessary for TCP client parameters.
  1508. Valid positional arguments to this function are host and port.
  1509. Valid keyword arguments to this function are all L{IReactorTCP.connectTCP}
  1510. arguments.
  1511. @return: The coerced values as a C{dict}.
  1512. """
  1513. if len(args) == 2:
  1514. kwargs["port"] = int(args[1])
  1515. kwargs["host"] = args[0]
  1516. elif len(args) == 1:
  1517. if "host" in kwargs:
  1518. kwargs["port"] = int(args[0])
  1519. else:
  1520. kwargs["host"] = args[0]
  1521. try:
  1522. kwargs["port"] = int(kwargs["port"])
  1523. except KeyError:
  1524. pass
  1525. try:
  1526. kwargs["timeout"] = int(kwargs["timeout"])
  1527. except KeyError:
  1528. pass
  1529. try:
  1530. kwargs["bindAddress"] = (kwargs["bindAddress"], 0)
  1531. except KeyError:
  1532. pass
  1533. return kwargs
  1534. def _loadCAsFromDir(directoryPath):
  1535. """
  1536. Load certificate-authority certificate objects in a given directory.
  1537. @param directoryPath: a L{unicode} or L{bytes} pointing at a directory to
  1538. load .pem files from, or L{None}.
  1539. @return: an L{IOpenSSLTrustRoot} provider.
  1540. """
  1541. caCerts = {}
  1542. for child in directoryPath.children():
  1543. if not child.asTextMode().basename().split(".")[-1].lower() == "pem":
  1544. continue
  1545. try:
  1546. data = child.getContent()
  1547. except OSError:
  1548. # Permission denied, corrupt disk, we don't care.
  1549. continue
  1550. try:
  1551. theCert = Certificate.loadPEM(data)
  1552. except SSLError:
  1553. # Duplicate certificate, invalid certificate, etc. We don't care.
  1554. pass
  1555. else:
  1556. caCerts[theCert.digest()] = theCert
  1557. return trustRootFromCertificates(caCerts.values())
  1558. def _parseTrustRootPath(pathName):
  1559. """
  1560. Parse a string referring to a directory full of certificate authorities
  1561. into a trust root.
  1562. @param pathName: path name
  1563. @type pathName: L{unicode} or L{bytes} or L{None}
  1564. @return: L{None} or L{IOpenSSLTrustRoot}
  1565. """
  1566. if pathName is None:
  1567. return None
  1568. return _loadCAsFromDir(FilePath(pathName))
  1569. def _privateCertFromPaths(certificatePath, keyPath):
  1570. """
  1571. Parse a certificate path and key path, either or both of which might be
  1572. L{None}, into a certificate object.
  1573. @param certificatePath: the certificate path
  1574. @type certificatePath: L{bytes} or L{unicode} or L{None}
  1575. @param keyPath: the private key path
  1576. @type keyPath: L{bytes} or L{unicode} or L{None}
  1577. @return: a L{PrivateCertificate} or L{None}
  1578. """
  1579. if certificatePath is None:
  1580. return None
  1581. certBytes = FilePath(certificatePath).getContent()
  1582. if keyPath is None:
  1583. return PrivateCertificate.loadPEM(certBytes)
  1584. else:
  1585. return PrivateCertificate.fromCertificateAndKeyPair(
  1586. Certificate.loadPEM(certBytes),
  1587. KeyPair.load(FilePath(keyPath).getContent(), 1),
  1588. )
  1589. def _parseClientSSLOptions(kwargs):
  1590. """
  1591. Parse common arguments for SSL endpoints, creating an L{CertificateOptions}
  1592. instance.
  1593. @param kwargs: A dict of keyword arguments to be parsed, potentially
  1594. containing keys C{certKey}, C{privateKey}, C{caCertsDir}, and
  1595. C{hostname}. See L{_parseClientSSL}.
  1596. @type kwargs: L{dict}
  1597. @return: The remaining arguments, including a new key C{sslContextFactory}.
  1598. """
  1599. hostname = kwargs.pop("hostname", None)
  1600. clientCertificate = _privateCertFromPaths(
  1601. kwargs.pop("certKey", None), kwargs.pop("privateKey", None)
  1602. )
  1603. trustRoot = _parseTrustRootPath(kwargs.pop("caCertsDir", None))
  1604. if hostname is not None:
  1605. configuration = optionsForClientTLS(
  1606. _idnaText(hostname),
  1607. trustRoot=trustRoot,
  1608. clientCertificate=clientCertificate,
  1609. )
  1610. else:
  1611. # _really_ though, you should specify a hostname.
  1612. if clientCertificate is not None:
  1613. privateKeyOpenSSL = clientCertificate.privateKey.original
  1614. certificateOpenSSL = clientCertificate.original
  1615. else:
  1616. privateKeyOpenSSL = None
  1617. certificateOpenSSL = None
  1618. configuration = CertificateOptions(
  1619. trustRoot=trustRoot,
  1620. privateKey=privateKeyOpenSSL,
  1621. certificate=certificateOpenSSL,
  1622. )
  1623. kwargs["sslContextFactory"] = configuration
  1624. return kwargs
  1625. def _parseClientSSL(*args, **kwargs):
  1626. """
  1627. Perform any argument value coercion necessary for SSL client parameters.
  1628. Valid keyword arguments to this function are all L{IReactorSSL.connectSSL}
  1629. arguments except for C{contextFactory}. Instead, C{certKey} (the path name
  1630. of the certificate file) C{privateKey} (the path name of the private key
  1631. associated with the certificate) are accepted and used to construct a
  1632. context factory.
  1633. Valid positional arguments to this function are host and port.
  1634. @keyword caCertsDir: The one parameter which is not part of
  1635. L{IReactorSSL.connectSSL}'s signature, this is a path name used to
  1636. construct a list of certificate authority certificates. The directory
  1637. will be scanned for files ending in C{.pem}, all of which will be
  1638. considered valid certificate authorities for this connection.
  1639. @type caCertsDir: L{str}
  1640. @keyword hostname: The hostname to use for validating the server's
  1641. certificate.
  1642. @type hostname: L{unicode}
  1643. @return: The coerced values as a L{dict}.
  1644. """
  1645. kwargs = _parseClientTCP(*args, **kwargs)
  1646. return _parseClientSSLOptions(kwargs)
  1647. def _parseClientUNIX(*args, **kwargs):
  1648. """
  1649. Perform any argument value coercion necessary for UNIX client parameters.
  1650. Valid keyword arguments to this function are all L{IReactorUNIX.connectUNIX}
  1651. keyword arguments except for C{checkPID}. Instead, C{lockfile} is accepted
  1652. and has the same meaning. Also C{path} is used instead of C{address}.
  1653. Valid positional arguments to this function are C{path}.
  1654. @return: The coerced values as a C{dict}.
  1655. """
  1656. if len(args) == 1:
  1657. kwargs["path"] = args[0]
  1658. try:
  1659. kwargs["checkPID"] = bool(int(kwargs.pop("lockfile")))
  1660. except KeyError:
  1661. pass
  1662. try:
  1663. kwargs["timeout"] = int(kwargs["timeout"])
  1664. except KeyError:
  1665. pass
  1666. return kwargs
  1667. _clientParsers = {
  1668. "TCP": _parseClientTCP,
  1669. "SSL": _parseClientSSL,
  1670. "UNIX": _parseClientUNIX,
  1671. }
  1672. def clientFromString(reactor, description):
  1673. """
  1674. Construct a client endpoint from a description string.
  1675. Client description strings are much like server description strings,
  1676. although they take all of their arguments as keywords, aside from host and
  1677. port.
  1678. You can create a TCP client endpoint with the 'host' and 'port' arguments,
  1679. like so::
  1680. clientFromString(reactor, "tcp:host=www.example.com:port=80")
  1681. or, without specifying host and port keywords::
  1682. clientFromString(reactor, "tcp:www.example.com:80")
  1683. Or you can specify only one or the other, as in the following 2 examples::
  1684. clientFromString(reactor, "tcp:host=www.example.com:80")
  1685. clientFromString(reactor, "tcp:www.example.com:port=80")
  1686. or an SSL client endpoint with those arguments, plus the arguments used by
  1687. the server SSL, for a client certificate::
  1688. clientFromString(reactor, "ssl:web.example.com:443:"
  1689. "privateKey=foo.pem:certKey=foo.pem")
  1690. to specify your certificate trust roots, you can identify a directory with
  1691. PEM files in it with the C{caCertsDir} argument::
  1692. clientFromString(reactor, "ssl:host=web.example.com:port=443:"
  1693. "caCertsDir=/etc/ssl/certs")
  1694. Both TCP and SSL client endpoint description strings can include a
  1695. 'bindAddress' keyword argument, whose value should be a local IPv4
  1696. address. This fixes the client socket to that IP address::
  1697. clientFromString(reactor, "tcp:www.example.com:80:"
  1698. "bindAddress=192.0.2.100")
  1699. NB: Fixed client ports are not currently supported in TCP or SSL
  1700. client endpoints. The client socket will always use an ephemeral
  1701. port assigned by the operating system
  1702. You can create a UNIX client endpoint with the 'path' argument and optional
  1703. 'lockfile' and 'timeout' arguments::
  1704. clientFromString(
  1705. reactor, b"unix:path=/var/foo/bar:lockfile=1:timeout=9")
  1706. or, with the path as a positional argument with or without optional
  1707. arguments as in the following 2 examples::
  1708. clientFromString(reactor, "unix:/var/foo/bar")
  1709. clientFromString(reactor, "unix:/var/foo/bar:lockfile=1:timeout=9")
  1710. This function is also extensible; new endpoint types may be registered as
  1711. L{IStreamClientEndpointStringParserWithReactor} plugins. See that
  1712. interface for more information.
  1713. @param reactor: The client endpoint will be constructed with this reactor.
  1714. @param description: The strports description to parse.
  1715. @type description: L{str}
  1716. @return: A new endpoint which can be used to connect with the parameters
  1717. given by C{description}.
  1718. @rtype: L{IStreamClientEndpoint<twisted.internet.interfaces.IStreamClientEndpoint>}
  1719. @since: 10.2
  1720. """
  1721. args, kwargs = _parse(description)
  1722. aname = args.pop(0)
  1723. name = aname.upper()
  1724. if name not in _clientParsers:
  1725. plugin = _matchPluginToPrefix(
  1726. getPlugins(IStreamClientEndpointStringParserWithReactor), name
  1727. )
  1728. return plugin.parseStreamClient(reactor, *args, **kwargs)
  1729. kwargs = _clientParsers[name](*args, **kwargs)
  1730. return _endpointClientFactories[name](reactor, **kwargs)
  1731. def connectProtocol(endpoint, protocol):
  1732. """
  1733. Connect a protocol instance to an endpoint.
  1734. This allows using a client endpoint without having to create a factory.
  1735. @param endpoint: A client endpoint to connect to.
  1736. @param protocol: A protocol instance.
  1737. @return: The result of calling C{connect} on the endpoint, i.e. a
  1738. L{Deferred} that will fire with the protocol when connected, or an
  1739. appropriate error.
  1740. @since: 13.1
  1741. """
  1742. class OneShotFactory(Factory):
  1743. def buildProtocol(self, addr):
  1744. return protocol
  1745. return endpoint.connect(OneShotFactory())
  1746. @implementer(interfaces.IStreamClientEndpoint)
  1747. class _WrapperEndpoint:
  1748. """
  1749. An endpoint that wraps another endpoint.
  1750. """
  1751. def __init__(self, wrappedEndpoint, wrapperFactory):
  1752. """
  1753. Construct a L{_WrapperEndpoint}.
  1754. """
  1755. self._wrappedEndpoint = wrappedEndpoint
  1756. self._wrapperFactory = wrapperFactory
  1757. def connect(self, protocolFactory):
  1758. """
  1759. Connect the given protocol factory and unwrap its result.
  1760. """
  1761. return self._wrappedEndpoint.connect(
  1762. self._wrapperFactory(protocolFactory)
  1763. ).addCallback(lambda protocol: protocol.wrappedProtocol)
  1764. @implementer(interfaces.IStreamServerEndpoint)
  1765. class _WrapperServerEndpoint:
  1766. """
  1767. A server endpoint that wraps another server endpoint.
  1768. """
  1769. def __init__(self, wrappedEndpoint, wrapperFactory):
  1770. """
  1771. Construct a L{_WrapperServerEndpoint}.
  1772. """
  1773. self._wrappedEndpoint = wrappedEndpoint
  1774. self._wrapperFactory = wrapperFactory
  1775. def listen(self, protocolFactory):
  1776. """
  1777. Connect the given protocol factory and unwrap its result.
  1778. """
  1779. return self._wrappedEndpoint.listen(self._wrapperFactory(protocolFactory))
  1780. def wrapClientTLS(connectionCreator, wrappedEndpoint):
  1781. """
  1782. Wrap an endpoint which upgrades to TLS as soon as the connection is
  1783. established.
  1784. @since: 16.0
  1785. @param connectionCreator: The TLS options to use when connecting; see
  1786. L{twisted.internet.ssl.optionsForClientTLS} for how to construct this.
  1787. @type connectionCreator:
  1788. L{twisted.internet.interfaces.IOpenSSLClientConnectionCreator}
  1789. @param wrappedEndpoint: The endpoint to wrap.
  1790. @type wrappedEndpoint: An L{IStreamClientEndpoint} provider.
  1791. @return: an endpoint that provides transport level encryption layered on
  1792. top of C{wrappedEndpoint}
  1793. @rtype: L{twisted.internet.interfaces.IStreamClientEndpoint}
  1794. """
  1795. if TLSMemoryBIOFactory is None:
  1796. raise NotImplementedError(
  1797. "OpenSSL not available. Try `pip install twisted[tls]`."
  1798. )
  1799. return _WrapperEndpoint(
  1800. wrappedEndpoint,
  1801. lambda protocolFactory: TLSMemoryBIOFactory(
  1802. connectionCreator, True, protocolFactory
  1803. ),
  1804. )
  1805. def _parseClientTLS(
  1806. reactor,
  1807. host,
  1808. port,
  1809. timeout=b"30",
  1810. bindAddress=None,
  1811. certificate=None,
  1812. privateKey=None,
  1813. trustRoots=None,
  1814. endpoint=None,
  1815. **kwargs,
  1816. ):
  1817. """
  1818. Internal method to construct an endpoint from string parameters.
  1819. @param reactor: The reactor passed to L{clientFromString}.
  1820. @param host: The hostname to connect to.
  1821. @type host: L{bytes} or L{unicode}
  1822. @param port: The port to connect to.
  1823. @type port: L{bytes} or L{unicode}
  1824. @param timeout: For each individual connection attempt, the number of
  1825. seconds to wait before assuming the connection has failed.
  1826. @type timeout: L{bytes} or L{unicode}
  1827. @param bindAddress: The address to which to bind outgoing connections.
  1828. @type bindAddress: L{bytes} or L{unicode}
  1829. @param certificate: a string representing a filesystem path to a
  1830. PEM-encoded certificate.
  1831. @type certificate: L{bytes} or L{unicode}
  1832. @param privateKey: a string representing a filesystem path to a PEM-encoded
  1833. certificate.
  1834. @type privateKey: L{bytes} or L{unicode}
  1835. @param endpoint: an optional string endpoint description of an endpoint to
  1836. wrap; if this is passed then C{host} is used only for certificate
  1837. verification.
  1838. @type endpoint: L{bytes} or L{unicode}
  1839. @return: a client TLS endpoint
  1840. @rtype: L{IStreamClientEndpoint}
  1841. """
  1842. if kwargs:
  1843. raise TypeError("unrecognized keyword arguments present", list(kwargs.keys()))
  1844. host = host if isinstance(host, str) else host.decode("utf-8")
  1845. bindAddress = (
  1846. bindAddress
  1847. if isinstance(bindAddress, str) or bindAddress is None
  1848. else bindAddress.decode("utf-8")
  1849. )
  1850. port = int(port)
  1851. timeout = int(timeout)
  1852. return wrapClientTLS(
  1853. optionsForClientTLS(
  1854. host,
  1855. trustRoot=_parseTrustRootPath(trustRoots),
  1856. clientCertificate=_privateCertFromPaths(certificate, privateKey),
  1857. ),
  1858. clientFromString(reactor, endpoint)
  1859. if endpoint is not None
  1860. else HostnameEndpoint(reactor, _idnaBytes(host), port, timeout, bindAddress),
  1861. )
  1862. @implementer(IPlugin, IStreamClientEndpointStringParserWithReactor)
  1863. class _TLSClientEndpointParser:
  1864. """
  1865. Stream client endpoint string parser for L{wrapClientTLS} with
  1866. L{HostnameEndpoint}.
  1867. @ivar prefix: See
  1868. L{IStreamClientEndpointStringParserWithReactor.prefix}.
  1869. """
  1870. prefix = "tls"
  1871. @staticmethod
  1872. def parseStreamClient(reactor, *args, **kwargs):
  1873. """
  1874. Redirects to another function L{_parseClientTLS}; tricks zope.interface
  1875. into believing the interface is correctly implemented, since the
  1876. signature is (C{reactor}, C{*args}, C{**kwargs}). See
  1877. L{_parseClientTLS} for the specific signature description for this
  1878. endpoint parser.
  1879. @param reactor: The reactor passed to L{clientFromString}.
  1880. @param args: The positional arguments in the endpoint description.
  1881. @type args: L{tuple}
  1882. @param kwargs: The named arguments in the endpoint description.
  1883. @type kwargs: L{dict}
  1884. @return: a client TLS endpoint
  1885. @rtype: L{IStreamClientEndpoint}
  1886. """
  1887. return _parseClientTLS(reactor, *args, **kwargs)