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.

amp.py 94KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065206620672068206920702071207220732074207520762077207820792080208120822083208420852086208720882089209020912092209320942095209620972098209921002101210221032104210521062107210821092110211121122113211421152116211721182119212021212122212321242125212621272128212921302131213221332134213521362137213821392140214121422143214421452146214721482149215021512152215321542155215621572158215921602161216221632164216521662167216821692170217121722173217421752176217721782179218021812182218321842185218621872188218921902191219221932194219521962197219821992200220122022203220422052206220722082209221022112212221322142215221622172218221922202221222222232224222522262227222822292230223122322233223422352236223722382239224022412242224322442245224622472248224922502251225222532254225522562257225822592260226122622263226422652266226722682269227022712272227322742275227622772278227922802281228222832284228522862287228822892290229122922293229422952296229722982299230023012302230323042305230623072308230923102311231223132314231523162317231823192320232123222323232423252326232723282329233023312332233323342335233623372338233923402341234223432344234523462347234823492350235123522353235423552356235723582359236023612362236323642365236623672368236923702371237223732374237523762377237823792380238123822383238423852386238723882389239023912392239323942395239623972398239924002401240224032404240524062407240824092410241124122413241424152416241724182419242024212422242324242425242624272428242924302431243224332434243524362437243824392440244124422443244424452446244724482449245024512452245324542455245624572458245924602461246224632464246524662467246824692470247124722473247424752476247724782479248024812482248324842485248624872488248924902491249224932494249524962497249824992500250125022503250425052506250725082509251025112512251325142515251625172518251925202521252225232524252525262527252825292530253125322533253425352536253725382539254025412542254325442545254625472548254925502551255225532554255525562557255825592560256125622563256425652566256725682569257025712572257325742575257625772578257925802581258225832584258525862587258825892590259125922593259425952596259725982599260026012602260326042605260626072608260926102611261226132614261526162617261826192620262126222623262426252626262726282629263026312632263326342635263626372638263926402641264226432644264526462647264826492650265126522653265426552656265726582659266026612662266326642665266626672668266926702671267226732674267526762677267826792680268126822683268426852686268726882689269026912692269326942695269626972698269927002701270227032704270527062707270827092710271127122713271427152716271727182719272027212722272327242725272627272728272927302731273227332734273527362737273827392740274127422743274427452746274727482749275027512752275327542755275627572758275927602761276227632764276527662767276827692770277127722773277427752776277727782779278027812782278327842785278627872788278927902791279227932794279527962797279827992800280128022803280428052806280728082809281028112812281328142815281628172818281928202821282228232824282528262827282828292830
  1. # -*- test-case-name: twisted.test.test_amp -*-
  2. # Copyright (c) 2005 Divmod, Inc.
  3. # Copyright (c) Twisted Matrix Laboratories.
  4. # See LICENSE for details.
  5. """
  6. This module implements AMP, the Asynchronous Messaging Protocol.
  7. AMP is a protocol for sending multiple asynchronous request/response pairs over
  8. the same connection. Requests and responses are both collections of key/value
  9. pairs.
  10. AMP is a very simple protocol which is not an application. This module is a
  11. "protocol construction kit" of sorts; it attempts to be the simplest wire-level
  12. implementation of Deferreds. AMP provides the following base-level features:
  13. - Asynchronous request/response handling (hence the name)
  14. - Requests and responses are both key/value pairs
  15. - Binary transfer of all data: all data is length-prefixed. Your
  16. application will never need to worry about quoting.
  17. - Command dispatching (like HTTP Verbs): the protocol is extensible, and
  18. multiple AMP sub-protocols can be grouped together easily.
  19. The protocol implementation also provides a few additional features which are
  20. not part of the core wire protocol, but are nevertheless very useful:
  21. - Tight TLS integration, with an included StartTLS command.
  22. - Handshaking to other protocols: because AMP has well-defined message
  23. boundaries and maintains all incoming and outgoing requests for you, you
  24. can start a connection over AMP and then switch to another protocol.
  25. This makes it ideal for firewall-traversal applications where you may
  26. have only one forwarded port but multiple applications that want to use
  27. it.
  28. Using AMP with Twisted is simple. Each message is a command, with a response.
  29. You begin by defining a command type. Commands specify their input and output
  30. in terms of the types that they expect to see in the request and response
  31. key-value pairs. Here's an example of a command that adds two integers, 'a'
  32. and 'b'::
  33. class Sum(amp.Command):
  34. arguments = [('a', amp.Integer()),
  35. ('b', amp.Integer())]
  36. response = [('total', amp.Integer())]
  37. Once you have specified a command, you need to make it part of a protocol, and
  38. define a responder for it. Here's a 'JustSum' protocol that includes a
  39. responder for our 'Sum' command::
  40. class JustSum(amp.AMP):
  41. def sum(self, a, b):
  42. total = a + b
  43. print 'Did a sum: %d + %d = %d' % (a, b, total)
  44. return {'total': total}
  45. Sum.responder(sum)
  46. Later, when you want to actually do a sum, the following expression will return
  47. a L{Deferred} which will fire with the result::
  48. ClientCreator(reactor, amp.AMP).connectTCP(...).addCallback(
  49. lambda p: p.callRemote(Sum, a=13, b=81)).addCallback(
  50. lambda result: result['total'])
  51. Command responders may also return Deferreds, causing the response to be
  52. sent only once the Deferred fires::
  53. class DelayedSum(amp.AMP):
  54. def slowSum(self, a, b):
  55. total = a + b
  56. result = defer.Deferred()
  57. reactor.callLater(3, result.callback, {'total': total})
  58. return result
  59. Sum.responder(slowSum)
  60. This is transparent to the caller.
  61. You can also define the propagation of specific errors in AMP. For example,
  62. for the slightly more complicated case of division, we might have to deal with
  63. division by zero::
  64. class Divide(amp.Command):
  65. arguments = [('numerator', amp.Integer()),
  66. ('denominator', amp.Integer())]
  67. response = [('result', amp.Float())]
  68. errors = {ZeroDivisionError: 'ZERO_DIVISION'}
  69. The 'errors' mapping here tells AMP that if a responder to Divide emits a
  70. L{ZeroDivisionError}, then the other side should be informed that an error of
  71. the type 'ZERO_DIVISION' has occurred. Writing a responder which takes
  72. advantage of this is very simple - just raise your exception normally::
  73. class JustDivide(amp.AMP):
  74. def divide(self, numerator, denominator):
  75. result = numerator / denominator
  76. print 'Divided: %d / %d = %d' % (numerator, denominator, total)
  77. return {'result': result}
  78. Divide.responder(divide)
  79. On the client side, the errors mapping will be used to determine what the
  80. 'ZERO_DIVISION' error means, and translated into an asynchronous exception,
  81. which can be handled normally as any L{Deferred} would be::
  82. def trapZero(result):
  83. result.trap(ZeroDivisionError)
  84. print "Divided by zero: returning INF"
  85. return 1e1000
  86. ClientCreator(reactor, amp.AMP).connectTCP(...).addCallback(
  87. lambda p: p.callRemote(Divide, numerator=1234,
  88. denominator=0)
  89. ).addErrback(trapZero)
  90. For a complete, runnable example of both of these commands, see the files in
  91. the Twisted repository::
  92. doc/core/examples/ampserver.py
  93. doc/core/examples/ampclient.py
  94. On the wire, AMP is a protocol which uses 2-byte lengths to prefix keys and
  95. values, and empty keys to separate messages::
  96. <2-byte length><key><2-byte length><value>
  97. <2-byte length><key><2-byte length><value>
  98. ...
  99. <2-byte length><key><2-byte length><value>
  100. <NUL><NUL> # Empty Key == End of Message
  101. And so on. Because it's tedious to refer to lengths and NULs constantly, the
  102. documentation will refer to packets as if they were newline delimited, like
  103. so::
  104. C: _command: sum
  105. C: _ask: ef639e5c892ccb54
  106. C: a: 13
  107. C: b: 81
  108. S: _answer: ef639e5c892ccb54
  109. S: total: 94
  110. Notes:
  111. In general, the order of keys is arbitrary. Specific uses of AMP may impose an
  112. ordering requirement, but unless this is specified explicitly, any ordering may
  113. be generated and any ordering must be accepted. This applies to the
  114. command-related keys I{_command} and I{_ask} as well as any other keys.
  115. Values are limited to the maximum encodable size in a 16-bit length, 65535
  116. bytes.
  117. Keys are limited to the maximum encodable size in a 8-bit length, 255 bytes.
  118. Note that we still use 2-byte lengths to encode keys. This small redundancy
  119. has several features:
  120. - If an implementation becomes confused and starts emitting corrupt data,
  121. or gets keys confused with values, many common errors will be signalled
  122. immediately instead of delivering obviously corrupt packets.
  123. - A single NUL will separate every key, and a double NUL separates
  124. messages. This provides some redundancy when debugging traffic dumps.
  125. - NULs will be present at regular intervals along the protocol, providing
  126. some padding for otherwise braindead C implementations of the protocol,
  127. so that <stdio.h> string functions will see the NUL and stop.
  128. - This makes it possible to run an AMP server on a port also used by a
  129. plain-text protocol, and easily distinguish between non-AMP clients (like
  130. web browsers) which issue non-NUL as the first byte, and AMP clients,
  131. which always issue NUL as the first byte.
  132. @var MAX_VALUE_LENGTH: The maximum length of a message.
  133. @type MAX_VALUE_LENGTH: L{int}
  134. @var ASK: Marker for an Ask packet.
  135. @type ASK: L{bytes}
  136. @var ANSWER: Marker for an Answer packet.
  137. @type ANSWER: L{bytes}
  138. @var COMMAND: Marker for a Command packet.
  139. @type COMMAND: L{bytes}
  140. @var ERROR: Marker for an AMP box of error type.
  141. @type ERROR: L{bytes}
  142. @var ERROR_CODE: Marker for an AMP box containing the code of an error.
  143. @type ERROR_CODE: L{bytes}
  144. @var ERROR_DESCRIPTION: Marker for an AMP box containing the description of the
  145. error.
  146. @type ERROR_DESCRIPTION: L{bytes}
  147. """
  148. import datetime
  149. import decimal
  150. import warnings
  151. from functools import partial
  152. from io import BytesIO
  153. from itertools import count
  154. from struct import pack
  155. from types import MethodType
  156. from typing import Any, Callable, Dict, List, Optional, Tuple, Type, Union
  157. from zope.interface import Interface, implementer
  158. from twisted.internet.defer import Deferred, fail, maybeDeferred
  159. from twisted.internet.error import ConnectionClosed, ConnectionLost, PeerVerifyError
  160. from twisted.internet.interfaces import IFileDescriptorReceiver
  161. from twisted.internet.main import CONNECTION_LOST
  162. from twisted.internet.protocol import Protocol
  163. from twisted.protocols.basic import Int16StringReceiver, StatefulStringProtocol
  164. from twisted.python import filepath, log
  165. from twisted.python._tzhelper import (
  166. UTC as utc,
  167. FixedOffsetTimeZone as _FixedOffsetTZInfo,
  168. )
  169. from twisted.python.compat import nativeString
  170. from twisted.python.failure import Failure
  171. from twisted.python.reflect import accumulateClassDict
  172. try:
  173. from twisted.internet import ssl as _ssl
  174. if _ssl.supported:
  175. from twisted.internet.ssl import DN, Certificate, CertificateOptions, KeyPair
  176. else:
  177. ssl = None
  178. except ImportError:
  179. ssl = None
  180. else:
  181. ssl = _ssl
  182. __all__ = [
  183. "AMP",
  184. "ANSWER",
  185. "ASK",
  186. "AmpBox",
  187. "AmpError",
  188. "AmpList",
  189. "Argument",
  190. "BadLocalReturn",
  191. "BinaryBoxProtocol",
  192. "Boolean",
  193. "Box",
  194. "BoxDispatcher",
  195. "COMMAND",
  196. "Command",
  197. "CommandLocator",
  198. "Decimal",
  199. "Descriptor",
  200. "ERROR",
  201. "ERROR_CODE",
  202. "ERROR_DESCRIPTION",
  203. "Float",
  204. "IArgumentType",
  205. "IBoxReceiver",
  206. "IBoxSender",
  207. "IResponderLocator",
  208. "IncompatibleVersions",
  209. "Integer",
  210. "InvalidSignature",
  211. "ListOf",
  212. "MAX_KEY_LENGTH",
  213. "MAX_VALUE_LENGTH",
  214. "MalformedAmpBox",
  215. "NoEmptyBoxes",
  216. "OnlyOneTLS",
  217. "PROTOCOL_ERRORS",
  218. "PYTHON_KEYWORDS",
  219. "Path",
  220. "ProtocolSwitchCommand",
  221. "ProtocolSwitched",
  222. "QuitBox",
  223. "RemoteAmpError",
  224. "SimpleStringLocator",
  225. "StartTLS",
  226. "String",
  227. "TooLong",
  228. "UNHANDLED_ERROR_CODE",
  229. "UNKNOWN_ERROR_CODE",
  230. "UnhandledCommand",
  231. "utc",
  232. "Unicode",
  233. "UnknownRemoteError",
  234. "parse",
  235. "parseString",
  236. ]
  237. ASK = b"_ask"
  238. ANSWER = b"_answer"
  239. COMMAND = b"_command"
  240. ERROR = b"_error"
  241. ERROR_CODE = b"_error_code"
  242. ERROR_DESCRIPTION = b"_error_description"
  243. UNKNOWN_ERROR_CODE = b"UNKNOWN"
  244. UNHANDLED_ERROR_CODE = b"UNHANDLED"
  245. MAX_KEY_LENGTH = 0xFF
  246. MAX_VALUE_LENGTH = 0xFFFF
  247. class IArgumentType(Interface):
  248. """
  249. An L{IArgumentType} can serialize a Python object into an AMP box and
  250. deserialize information from an AMP box back into a Python object.
  251. @since: 9.0
  252. """
  253. def fromBox(name, strings, objects, proto):
  254. """
  255. Given an argument name and an AMP box containing serialized values,
  256. extract one or more Python objects and add them to the C{objects}
  257. dictionary.
  258. @param name: The name associated with this argument. Most commonly
  259. this is the key which can be used to find a serialized value in
  260. C{strings}.
  261. @type name: C{bytes}
  262. @param strings: The AMP box from which to extract one or more
  263. values.
  264. @type strings: C{dict}
  265. @param objects: The output dictionary to populate with the value for
  266. this argument. The key used will be derived from C{name}. It may
  267. differ; in Python 3, for example, the key will be a Unicode/native
  268. string. See L{_wireNameToPythonIdentifier}.
  269. @type objects: C{dict}
  270. @param proto: The protocol instance which received the AMP box being
  271. interpreted. Most likely this is an instance of L{AMP}, but
  272. this is not guaranteed.
  273. @return: L{None}
  274. """
  275. def toBox(name, strings, objects, proto):
  276. """
  277. Given an argument name and a dictionary containing structured Python
  278. objects, serialize values into one or more strings and add them to
  279. the C{strings} dictionary.
  280. @param name: The name associated with this argument. Most commonly
  281. this is the key in C{strings} to associate with a C{bytes} giving
  282. the serialized form of that object.
  283. @type name: C{bytes}
  284. @param strings: The AMP box into which to insert one or more strings.
  285. @type strings: C{dict}
  286. @param objects: The input dictionary from which to extract Python
  287. objects to serialize. The key used will be derived from C{name}.
  288. It may differ; in Python 3, for example, the key will be a
  289. Unicode/native string. See L{_wireNameToPythonIdentifier}.
  290. @type objects: C{dict}
  291. @param proto: The protocol instance which will send the AMP box once
  292. it is fully populated. Most likely this is an instance of
  293. L{AMP}, but this is not guaranteed.
  294. @return: L{None}
  295. """
  296. class IBoxSender(Interface):
  297. """
  298. A transport which can send L{AmpBox} objects.
  299. """
  300. def sendBox(box):
  301. """
  302. Send an L{AmpBox}.
  303. @raise ProtocolSwitched: if the underlying protocol has been
  304. switched.
  305. @raise ConnectionLost: if the underlying connection has already been
  306. lost.
  307. """
  308. def unhandledError(failure):
  309. """
  310. An unhandled error occurred in response to a box. Log it
  311. appropriately.
  312. @param failure: a L{Failure} describing the error that occurred.
  313. """
  314. class IBoxReceiver(Interface):
  315. """
  316. An application object which can receive L{AmpBox} objects and dispatch them
  317. appropriately.
  318. """
  319. def startReceivingBoxes(boxSender):
  320. """
  321. The L{IBoxReceiver.ampBoxReceived} method will start being called;
  322. boxes may be responded to by responding to the given L{IBoxSender}.
  323. @param boxSender: an L{IBoxSender} provider.
  324. """
  325. def ampBoxReceived(box):
  326. """
  327. A box was received from the transport; dispatch it appropriately.
  328. """
  329. def stopReceivingBoxes(reason):
  330. """
  331. No further boxes will be received on this connection.
  332. @type reason: L{Failure}
  333. """
  334. class IResponderLocator(Interface):
  335. """
  336. An application object which can look up appropriate responder methods for
  337. AMP commands.
  338. """
  339. def locateResponder(name):
  340. """
  341. Locate a responder method appropriate for the named command.
  342. @param name: the wire-level name (commandName) of the AMP command to be
  343. responded to.
  344. @type name: C{bytes}
  345. @return: a 1-argument callable that takes an L{AmpBox} with argument
  346. values for the given command, and returns an L{AmpBox} containing
  347. argument values for the named command, or a L{Deferred} that fires the
  348. same.
  349. """
  350. class AmpError(Exception):
  351. """
  352. Base class of all Amp-related exceptions.
  353. """
  354. class ProtocolSwitched(Exception):
  355. """
  356. Connections which have been switched to other protocols can no longer
  357. accept traffic at the AMP level. This is raised when you try to send it.
  358. """
  359. class OnlyOneTLS(AmpError):
  360. """
  361. This is an implementation limitation; TLS may only be started once per
  362. connection.
  363. """
  364. class NoEmptyBoxes(AmpError):
  365. """
  366. You can't have empty boxes on the connection. This is raised when you
  367. receive or attempt to send one.
  368. """
  369. class InvalidSignature(AmpError):
  370. """
  371. You didn't pass all the required arguments.
  372. """
  373. class TooLong(AmpError):
  374. """
  375. One of the protocol's length limitations was violated.
  376. @ivar isKey: true if the string being encoded in a key position, false if
  377. it was in a value position.
  378. @ivar isLocal: Was the string encoded locally, or received too long from
  379. the network? (It's only physically possible to encode "too long" values on
  380. the network for keys.)
  381. @ivar value: The string that was too long.
  382. @ivar keyName: If the string being encoded was in a value position, what
  383. key was it being encoded for?
  384. """
  385. def __init__(self, isKey, isLocal, value, keyName=None):
  386. AmpError.__init__(self)
  387. self.isKey = isKey
  388. self.isLocal = isLocal
  389. self.value = value
  390. self.keyName = keyName
  391. def __repr__(self) -> str:
  392. hdr = self.isKey and "key" or "value"
  393. if not self.isKey:
  394. hdr += " " + repr(self.keyName)
  395. lcl = self.isLocal and "local" or "remote"
  396. return "%s %s too long: %d" % (lcl, hdr, len(self.value))
  397. class BadLocalReturn(AmpError):
  398. """
  399. A bad value was returned from a local command; we were unable to coerce it.
  400. """
  401. def __init__(self, message: str, enclosed: Failure) -> None:
  402. AmpError.__init__(self)
  403. self.message = message
  404. self.enclosed = enclosed
  405. def __repr__(self) -> str:
  406. return self.message + " " + self.enclosed.getBriefTraceback()
  407. __str__ = __repr__
  408. class RemoteAmpError(AmpError):
  409. """
  410. This error indicates that something went wrong on the remote end of the
  411. connection, and the error was serialized and transmitted to you.
  412. """
  413. def __init__(self, errorCode, description, fatal=False, local=None):
  414. """Create a remote error with an error code and description.
  415. @param errorCode: the AMP error code of this error.
  416. @type errorCode: C{bytes}
  417. @param description: some text to show to the user.
  418. @type description: C{str}
  419. @param fatal: a boolean, true if this error should terminate the
  420. connection.
  421. @param local: a local Failure, if one exists.
  422. """
  423. if local:
  424. localwhat = " (local)"
  425. othertb = local.getBriefTraceback()
  426. else:
  427. localwhat = ""
  428. othertb = ""
  429. # Backslash-escape errorCode. Python 3.5 can do this natively
  430. # ("backslashescape") but Python 2.7 and Python 3.4 can't.
  431. errorCodeForMessage = "".join(
  432. f"\\x{c:2x}" if c >= 0x80 else chr(c) for c in errorCode
  433. )
  434. if othertb:
  435. message = "Code<{}>{}: {}\n{}".format(
  436. errorCodeForMessage,
  437. localwhat,
  438. description,
  439. othertb,
  440. )
  441. else:
  442. message = "Code<{}>{}: {}".format(
  443. errorCodeForMessage, localwhat, description
  444. )
  445. super().__init__(message)
  446. self.local = local
  447. self.errorCode = errorCode
  448. self.description = description
  449. self.fatal = fatal
  450. class UnknownRemoteError(RemoteAmpError):
  451. """
  452. This means that an error whose type we can't identify was raised from the
  453. other side.
  454. """
  455. def __init__(self, description):
  456. errorCode = UNKNOWN_ERROR_CODE
  457. RemoteAmpError.__init__(self, errorCode, description)
  458. class MalformedAmpBox(AmpError):
  459. """
  460. This error indicates that the wire-level protocol was malformed.
  461. """
  462. class UnhandledCommand(AmpError):
  463. """
  464. A command received via amp could not be dispatched.
  465. """
  466. class IncompatibleVersions(AmpError):
  467. """
  468. It was impossible to negotiate a compatible version of the protocol with
  469. the other end of the connection.
  470. """
  471. PROTOCOL_ERRORS = {UNHANDLED_ERROR_CODE: UnhandledCommand}
  472. class AmpBox(dict):
  473. """
  474. I am a packet in the AMP protocol, much like a
  475. regular bytes:bytes dictionary.
  476. """
  477. # be like a regular dictionary don't magically
  478. # acquire a __dict__...
  479. __slots__: List[str] = []
  480. def __init__(self, *args, **kw):
  481. """
  482. Initialize a new L{AmpBox}.
  483. In Python 3, keyword arguments MUST be Unicode/native strings whereas
  484. in Python 2 they could be either byte strings or Unicode strings.
  485. However, all keys of an L{AmpBox} MUST be byte strings, or possible to
  486. transparently coerce into byte strings (i.e. Python 2).
  487. In Python 3, therefore, native string keys are coerced to byte strings
  488. by encoding as ASCII. This can result in C{UnicodeEncodeError} being
  489. raised.
  490. @param args: See C{dict}, but all keys and values should be C{bytes}.
  491. On Python 3, native strings may be used as keys provided they
  492. contain only ASCII characters.
  493. @param kw: See C{dict}, but all keys and values should be C{bytes}.
  494. On Python 3, native strings may be used as keys provided they
  495. contain only ASCII characters.
  496. @raise UnicodeEncodeError: When a native string key cannot be coerced
  497. to an ASCII byte string (Python 3 only).
  498. """
  499. super().__init__(*args, **kw)
  500. nonByteNames = [n for n in self if not isinstance(n, bytes)]
  501. for nonByteName in nonByteNames:
  502. byteName = nonByteName.encode("ascii")
  503. self[byteName] = self.pop(nonByteName)
  504. def copy(self):
  505. """
  506. Return another AmpBox just like me.
  507. """
  508. newBox = self.__class__()
  509. newBox.update(self)
  510. return newBox
  511. def serialize(self):
  512. """
  513. Convert me into a wire-encoded string.
  514. @return: a C{bytes} encoded according to the rules described in the
  515. module docstring.
  516. """
  517. i = sorted(self.items())
  518. L = []
  519. w = L.append
  520. for k, v in i:
  521. if type(k) == str:
  522. raise TypeError("Unicode key not allowed: %r" % k)
  523. if type(v) == str:
  524. raise TypeError(f"Unicode value for key {k!r} not allowed: {v!r}")
  525. if len(k) > MAX_KEY_LENGTH:
  526. raise TooLong(True, True, k, None)
  527. if len(v) > MAX_VALUE_LENGTH:
  528. raise TooLong(False, True, v, k)
  529. for kv in k, v:
  530. w(pack("!H", len(kv)))
  531. w(kv)
  532. w(pack("!H", 0))
  533. return b"".join(L)
  534. def _sendTo(self, proto):
  535. """
  536. Serialize and send this box to an Amp instance. By the time it is being
  537. sent, several keys are required. I must have exactly ONE of::
  538. _ask
  539. _answer
  540. _error
  541. If the '_ask' key is set, then the '_command' key must also be
  542. set.
  543. @param proto: an AMP instance.
  544. """
  545. proto.sendBox(self)
  546. def __repr__(self) -> str:
  547. return f"AmpBox({dict.__repr__(self)})"
  548. # amp.Box => AmpBox
  549. Box = AmpBox
  550. class QuitBox(AmpBox):
  551. """
  552. I am an AmpBox that, upon being sent, terminates the connection.
  553. """
  554. __slots__: List[str] = []
  555. def __repr__(self) -> str:
  556. return f"QuitBox(**{super().__repr__()})"
  557. def _sendTo(self, proto):
  558. """
  559. Immediately call loseConnection after sending.
  560. """
  561. super()._sendTo(proto)
  562. proto.transport.loseConnection()
  563. class _SwitchBox(AmpBox):
  564. """
  565. Implementation detail of ProtocolSwitchCommand: I am an AmpBox which sets
  566. up state for the protocol to switch.
  567. """
  568. # DON'T set __slots__ here; we do have an attribute.
  569. def __init__(self, innerProto, **kw):
  570. """
  571. Create a _SwitchBox with the protocol to switch to after being sent.
  572. @param innerProto: the protocol instance to switch to.
  573. @type innerProto: an IProtocol provider.
  574. """
  575. super().__init__(**kw)
  576. self.innerProto = innerProto
  577. def __repr__(self) -> str:
  578. return "_SwitchBox({!r}, **{})".format(
  579. self.innerProto,
  580. dict.__repr__(self),
  581. )
  582. def _sendTo(self, proto):
  583. """
  584. Send me; I am the last box on the connection. All further traffic will be
  585. over the new protocol.
  586. """
  587. super()._sendTo(proto)
  588. proto._lockForSwitch()
  589. proto._switchTo(self.innerProto)
  590. @implementer(IBoxReceiver)
  591. class BoxDispatcher:
  592. """
  593. A L{BoxDispatcher} dispatches '_ask', '_answer', and '_error' L{AmpBox}es,
  594. both incoming and outgoing, to their appropriate destinations.
  595. Outgoing commands are converted into L{Deferred}s and outgoing boxes, and
  596. associated tracking state to fire those L{Deferred} when '_answer' boxes
  597. come back. Incoming '_answer' and '_error' boxes are converted into
  598. callbacks and errbacks on those L{Deferred}s, respectively.
  599. Incoming '_ask' boxes are converted into method calls on a supplied method
  600. locator.
  601. @ivar _outstandingRequests: a dictionary mapping request IDs to
  602. L{Deferred}s which were returned for those requests.
  603. @ivar locator: an object with a L{CommandLocator.locateResponder} method
  604. that locates a responder function that takes a Box and returns a result
  605. (either a Box or a Deferred which fires one).
  606. @ivar boxSender: an object which can send boxes, via the L{_sendBoxCommand}
  607. method, such as an L{AMP} instance.
  608. @type boxSender: L{IBoxSender}
  609. """
  610. _failAllReason = None
  611. _outstandingRequests = None
  612. _counter = 0
  613. boxSender = None
  614. def __init__(self, locator):
  615. self._outstandingRequests = {}
  616. self.locator = locator
  617. def startReceivingBoxes(self, boxSender):
  618. """
  619. The given boxSender is going to start calling boxReceived on this
  620. L{BoxDispatcher}.
  621. @param boxSender: The L{IBoxSender} to send command responses to.
  622. """
  623. self.boxSender = boxSender
  624. def stopReceivingBoxes(self, reason):
  625. """
  626. No further boxes will be received here. Terminate all currently
  627. outstanding command deferreds with the given reason.
  628. """
  629. self.failAllOutgoing(reason)
  630. def failAllOutgoing(self, reason):
  631. """
  632. Call the errback on all outstanding requests awaiting responses.
  633. @param reason: the Failure instance to pass to those errbacks.
  634. """
  635. self._failAllReason = reason
  636. OR = self._outstandingRequests.items()
  637. self._outstandingRequests = None # we can never send another request
  638. for key, value in OR:
  639. value.errback(reason)
  640. def _nextTag(self):
  641. """
  642. Generate protocol-local serial numbers for _ask keys.
  643. @return: a string that has not yet been used on this connection.
  644. """
  645. self._counter += 1
  646. return b"%x" % (self._counter,)
  647. def _sendBoxCommand(self, command, box, requiresAnswer=True):
  648. """
  649. Send a command across the wire with the given C{amp.Box}.
  650. Mutate the given box to give it any additional keys (_command, _ask)
  651. required for the command and request/response machinery, then send it.
  652. If requiresAnswer is True, returns a C{Deferred} which fires when a
  653. response is received. The C{Deferred} is fired with an C{amp.Box} on
  654. success, or with an C{amp.RemoteAmpError} if an error is received.
  655. If the Deferred fails and the error is not handled by the caller of
  656. this method, the failure will be logged and the connection dropped.
  657. @param command: a C{bytes}, the name of the command to issue.
  658. @param box: an AmpBox with the arguments for the command.
  659. @param requiresAnswer: a boolean. Defaults to True. If True, return a
  660. Deferred which will fire when the other side responds to this command.
  661. If False, return None and do not ask the other side for acknowledgement.
  662. @return: a Deferred which fires the AmpBox that holds the response to
  663. this command, or None, as specified by requiresAnswer.
  664. @raise ProtocolSwitched: if the protocol has been switched.
  665. """
  666. if self._failAllReason is not None:
  667. if requiresAnswer:
  668. return fail(self._failAllReason)
  669. else:
  670. return None
  671. box[COMMAND] = command
  672. tag = self._nextTag()
  673. if requiresAnswer:
  674. box[ASK] = tag
  675. box._sendTo(self.boxSender)
  676. if requiresAnswer:
  677. result = self._outstandingRequests[tag] = Deferred()
  678. else:
  679. result = None
  680. return result
  681. def callRemoteString(self, command, requiresAnswer=True, **kw):
  682. """
  683. This is a low-level API, designed only for optimizing simple messages
  684. for which the overhead of parsing is too great.
  685. @param command: a C{bytes} naming the command.
  686. @param kw: arguments to the amp box.
  687. @param requiresAnswer: a boolean. Defaults to True. If True, return a
  688. Deferred which will fire when the other side responds to this command.
  689. If False, return None and do not ask the other side for acknowledgement.
  690. @return: a Deferred which fires the AmpBox that holds the response to
  691. this command, or None, as specified by requiresAnswer.
  692. """
  693. box = Box(kw)
  694. return self._sendBoxCommand(command, box, requiresAnswer)
  695. def callRemote(self, commandType, *a, **kw):
  696. """
  697. This is the primary high-level API for sending messages via AMP. Invoke it
  698. with a command and appropriate arguments to send a message to this
  699. connection's peer.
  700. @param commandType: a subclass of Command.
  701. @type commandType: L{type}
  702. @param a: Positional (special) parameters taken by the command.
  703. Positional parameters will typically not be sent over the wire. The
  704. only command included with AMP which uses positional parameters is
  705. L{ProtocolSwitchCommand}, which takes the protocol that will be
  706. switched to as its first argument.
  707. @param kw: Keyword arguments taken by the command. These are the
  708. arguments declared in the command's 'arguments' attribute. They will
  709. be encoded and sent to the peer as arguments for the L{commandType}.
  710. @return: If L{commandType} has a C{requiresAnswer} attribute set to
  711. L{False}, then return L{None}. Otherwise, return a L{Deferred} which
  712. fires with a dictionary of objects representing the result of this
  713. call. Additionally, this L{Deferred} may fail with an exception
  714. representing a connection failure, with L{UnknownRemoteError} if the
  715. other end of the connection fails for an unknown reason, or with any
  716. error specified as a key in L{commandType}'s C{errors} dictionary.
  717. """
  718. # XXX this takes command subclasses and not command objects on purpose.
  719. # There's really no reason to have all this back-and-forth between
  720. # command objects and the protocol, and the extra object being created
  721. # (the Command instance) is pointless. Command is kind of like
  722. # Interface, and should be more like it.
  723. # In other words, the fact that commandType is instantiated here is an
  724. # implementation detail. Don't rely on it.
  725. try:
  726. co = commandType(*a, **kw)
  727. except BaseException:
  728. return fail()
  729. return co._doCommand(self)
  730. def unhandledError(self, failure):
  731. """
  732. This is a terminal callback called after application code has had a
  733. chance to quash any errors.
  734. """
  735. return self.boxSender.unhandledError(failure)
  736. def _answerReceived(self, box):
  737. """
  738. An AMP box was received that answered a command previously sent with
  739. L{callRemote}.
  740. @param box: an AmpBox with a value for its L{ANSWER} key.
  741. """
  742. question = self._outstandingRequests.pop(box[ANSWER])
  743. question.addErrback(self.unhandledError)
  744. question.callback(box)
  745. def _errorReceived(self, box):
  746. """
  747. An AMP box was received that answered a command previously sent with
  748. L{callRemote}, with an error.
  749. @param box: an L{AmpBox} with a value for its L{ERROR}, L{ERROR_CODE},
  750. and L{ERROR_DESCRIPTION} keys.
  751. """
  752. question = self._outstandingRequests.pop(box[ERROR])
  753. question.addErrback(self.unhandledError)
  754. errorCode = box[ERROR_CODE]
  755. description = box[ERROR_DESCRIPTION]
  756. if isinstance(description, bytes):
  757. description = description.decode("utf-8", "replace")
  758. if errorCode in PROTOCOL_ERRORS:
  759. exc = PROTOCOL_ERRORS[errorCode](errorCode, description)
  760. else:
  761. exc = RemoteAmpError(errorCode, description)
  762. question.errback(Failure(exc))
  763. def _commandReceived(self, box):
  764. """
  765. @param box: an L{AmpBox} with a value for its L{COMMAND} and L{ASK}
  766. keys.
  767. """
  768. def formatAnswer(answerBox):
  769. answerBox[ANSWER] = box[ASK]
  770. return answerBox
  771. def formatError(error):
  772. if error.check(RemoteAmpError):
  773. code = error.value.errorCode
  774. desc = error.value.description
  775. if isinstance(desc, str):
  776. desc = desc.encode("utf-8", "replace")
  777. if error.value.fatal:
  778. errorBox = QuitBox()
  779. else:
  780. errorBox = AmpBox()
  781. else:
  782. errorBox = QuitBox()
  783. log.err(error) # here is where server-side logging happens
  784. # if the error isn't handled
  785. code = UNKNOWN_ERROR_CODE
  786. desc = b"Unknown Error"
  787. errorBox[ERROR] = box[ASK]
  788. errorBox[ERROR_DESCRIPTION] = desc
  789. errorBox[ERROR_CODE] = code
  790. return errorBox
  791. deferred = self.dispatchCommand(box)
  792. if ASK in box:
  793. deferred.addCallbacks(formatAnswer, formatError)
  794. deferred.addCallback(self._safeEmit)
  795. deferred.addErrback(self.unhandledError)
  796. def ampBoxReceived(self, box):
  797. """
  798. An AmpBox was received, representing a command, or an answer to a
  799. previously issued command (either successful or erroneous). Respond to
  800. it according to its contents.
  801. @param box: an AmpBox
  802. @raise NoEmptyBoxes: when a box is received that does not contain an
  803. '_answer', '_command' / '_ask', or '_error' key; i.e. one which does not
  804. fit into the command / response protocol defined by AMP.
  805. """
  806. if ANSWER in box:
  807. self._answerReceived(box)
  808. elif ERROR in box:
  809. self._errorReceived(box)
  810. elif COMMAND in box:
  811. self._commandReceived(box)
  812. else:
  813. raise NoEmptyBoxes(box)
  814. def _safeEmit(self, aBox):
  815. """
  816. Emit a box, ignoring L{ProtocolSwitched} and L{ConnectionLost} errors
  817. which cannot be usefully handled.
  818. """
  819. try:
  820. aBox._sendTo(self.boxSender)
  821. except (ProtocolSwitched, ConnectionLost):
  822. pass
  823. def dispatchCommand(self, box):
  824. """
  825. A box with a _command key was received.
  826. Dispatch it to a local handler call it.
  827. @param box: an AmpBox to be dispatched.
  828. """
  829. cmd = box[COMMAND]
  830. responder = self.locator.locateResponder(cmd)
  831. if responder is None:
  832. description = f"Unhandled Command: {cmd!r}"
  833. return fail(
  834. RemoteAmpError(
  835. UNHANDLED_ERROR_CODE,
  836. description,
  837. False,
  838. local=Failure(UnhandledCommand()),
  839. )
  840. )
  841. return maybeDeferred(responder, box)
  842. class _CommandLocatorMeta(type):
  843. """
  844. This metaclass keeps track of all of the Command.responder-decorated
  845. methods defined since the last CommandLocator subclass was defined. It
  846. assumes (usually correctly, but unfortunately not necessarily so) that
  847. those commands responders were all declared as methods of the class
  848. being defined. Note that this list can be incorrect if users use the
  849. Command.responder decorator outside the context of a CommandLocator
  850. class declaration.
  851. Command responders defined on subclasses are given precedence over
  852. those inherited from a base class.
  853. The Command.responder decorator explicitly cooperates with this
  854. metaclass.
  855. """
  856. _currentClassCommands: "List[Tuple[Command, Callable]]" = []
  857. def __new__(cls, name, bases, attrs):
  858. commands = cls._currentClassCommands[:]
  859. cls._currentClassCommands[:] = []
  860. cd = attrs["_commandDispatch"] = {}
  861. subcls = type.__new__(cls, name, bases, attrs)
  862. ancestors = list(subcls.__mro__[1:])
  863. ancestors.reverse()
  864. for ancestor in ancestors:
  865. cd.update(getattr(ancestor, "_commandDispatch", {}))
  866. for commandClass, responderFunc in commands:
  867. cd[commandClass.commandName] = (commandClass, responderFunc)
  868. if bases and (subcls.lookupFunction != CommandLocator.lookupFunction):
  869. def locateResponder(self, name):
  870. warnings.warn(
  871. "Override locateResponder, not lookupFunction.",
  872. category=PendingDeprecationWarning,
  873. stacklevel=2,
  874. )
  875. return self.lookupFunction(name)
  876. subcls.locateResponder = locateResponder
  877. return subcls
  878. @implementer(IResponderLocator)
  879. class CommandLocator(metaclass=_CommandLocatorMeta):
  880. """
  881. A L{CommandLocator} is a collection of responders to AMP L{Command}s, with
  882. the help of the L{Command.responder} decorator.
  883. """
  884. def _wrapWithSerialization(self, aCallable, command):
  885. """
  886. Wrap aCallable with its command's argument de-serialization
  887. and result serialization logic.
  888. @param aCallable: a callable with a 'command' attribute, designed to be
  889. called with keyword arguments.
  890. @param command: the command class whose serialization to use.
  891. @return: a 1-arg callable which, when invoked with an AmpBox, will
  892. deserialize the argument list and invoke appropriate user code for the
  893. callable's command, returning a Deferred which fires with the result or
  894. fails with an error.
  895. """
  896. def doit(box):
  897. kw = command.parseArguments(box, self)
  898. def checkKnownErrors(error):
  899. key = error.trap(*command.allErrors)
  900. code = command.allErrors[key]
  901. desc = str(error.value)
  902. return Failure(
  903. RemoteAmpError(code, desc, key in command.fatalErrors, local=error)
  904. )
  905. def makeResponseFor(objects):
  906. try:
  907. return command.makeResponse(objects, self)
  908. except BaseException:
  909. # let's helpfully log this.
  910. originalFailure = Failure()
  911. raise BadLocalReturn(
  912. "%r returned %r and %r could not serialize it"
  913. % (aCallable, objects, command),
  914. originalFailure,
  915. )
  916. return (
  917. maybeDeferred(aCallable, **kw)
  918. .addCallback(makeResponseFor)
  919. .addErrback(checkKnownErrors)
  920. )
  921. return doit
  922. def lookupFunction(self, name):
  923. """
  924. Deprecated synonym for L{CommandLocator.locateResponder}
  925. """
  926. if self.__class__.lookupFunction != CommandLocator.lookupFunction:
  927. return CommandLocator.locateResponder(self, name)
  928. else:
  929. warnings.warn(
  930. "Call locateResponder, not lookupFunction.",
  931. category=PendingDeprecationWarning,
  932. stacklevel=2,
  933. )
  934. return self.locateResponder(name)
  935. def locateResponder(self, name):
  936. """
  937. Locate a callable to invoke when executing the named command.
  938. @param name: the normalized name (from the wire) of the command.
  939. @type name: C{bytes}
  940. @return: a 1-argument function that takes a Box and returns a box or a
  941. Deferred which fires a Box, for handling the command identified by the
  942. given name, or None, if no appropriate responder can be found.
  943. """
  944. # Try to find a high-level method to invoke, and if we can't find one,
  945. # fall back to a low-level one.
  946. cd = self._commandDispatch
  947. if name in cd:
  948. commandClass, responderFunc = cd[name]
  949. responderMethod = MethodType(responderFunc, self)
  950. return self._wrapWithSerialization(responderMethod, commandClass)
  951. @implementer(IResponderLocator)
  952. class SimpleStringLocator:
  953. """
  954. Implement the L{AMP.locateResponder} method to do simple, string-based
  955. dispatch.
  956. """
  957. baseDispatchPrefix = b"amp_"
  958. def locateResponder(self, name):
  959. """
  960. Locate a callable to invoke when executing the named command.
  961. @return: a function with the name C{"amp_" + name} on the same
  962. instance, or None if no such function exists.
  963. This function will then be called with the L{AmpBox} itself as an
  964. argument.
  965. @param name: the normalized name (from the wire) of the command.
  966. @type name: C{bytes}
  967. """
  968. fName = nativeString(self.baseDispatchPrefix + name.upper())
  969. return getattr(self, fName, None)
  970. PYTHON_KEYWORDS = [
  971. "and",
  972. "del",
  973. "for",
  974. "is",
  975. "raise",
  976. "assert",
  977. "elif",
  978. "from",
  979. "lambda",
  980. "return",
  981. "break",
  982. "else",
  983. "global",
  984. "not",
  985. "try",
  986. "class",
  987. "except",
  988. "if",
  989. "or",
  990. "while",
  991. "continue",
  992. "exec",
  993. "import",
  994. "pass",
  995. "yield",
  996. "def",
  997. "finally",
  998. "in",
  999. "print",
  1000. ]
  1001. def _wireNameToPythonIdentifier(key):
  1002. """
  1003. (Private) Normalize an argument name from the wire for use with Python
  1004. code. If the return value is going to be a python keyword it will be
  1005. capitalized. If it contains any dashes they will be replaced with
  1006. underscores.
  1007. The rationale behind this method is that AMP should be an inherently
  1008. multi-language protocol, so message keys may contain all manner of bizarre
  1009. bytes. This is not a complete solution; there are still forms of arguments
  1010. that this implementation will be unable to parse. However, Python
  1011. identifiers share a huge raft of properties with identifiers from many
  1012. other languages, so this is a 'good enough' effort for now. We deal
  1013. explicitly with dashes because that is the most likely departure: Lisps
  1014. commonly use dashes to separate method names, so protocols initially
  1015. implemented in a lisp amp dialect may use dashes in argument or command
  1016. names.
  1017. @param key: a C{bytes}, looking something like 'foo-bar-baz' or 'from'
  1018. @type key: C{bytes}
  1019. @return: a native string which is a valid python identifier, looking
  1020. something like 'foo_bar_baz' or 'From'.
  1021. """
  1022. lkey = nativeString(key.replace(b"-", b"_"))
  1023. if lkey in PYTHON_KEYWORDS:
  1024. return lkey.title()
  1025. return lkey
  1026. @implementer(IArgumentType)
  1027. class Argument:
  1028. """
  1029. Base-class of all objects that take values from Amp packets and convert
  1030. them into objects for Python functions.
  1031. This implementation of L{IArgumentType} provides several higher-level
  1032. hooks for subclasses to override. See L{toString} and L{fromString}
  1033. which will be used to define the behavior of L{IArgumentType.toBox} and
  1034. L{IArgumentType.fromBox}, respectively.
  1035. """
  1036. optional = False
  1037. def __init__(self, optional=False):
  1038. """
  1039. Create an Argument.
  1040. @param optional: a boolean indicating whether this argument can be
  1041. omitted in the protocol.
  1042. """
  1043. self.optional = optional
  1044. def retrieve(self, d, name, proto):
  1045. """
  1046. Retrieve the given key from the given dictionary, removing it if found.
  1047. @param d: a dictionary.
  1048. @param name: a key in I{d}.
  1049. @param proto: an instance of an AMP.
  1050. @raise KeyError: if I am not optional and no value was found.
  1051. @return: d[name].
  1052. """
  1053. if self.optional:
  1054. value = d.get(name)
  1055. if value is not None:
  1056. del d[name]
  1057. else:
  1058. value = d.pop(name)
  1059. return value
  1060. def fromBox(self, name, strings, objects, proto):
  1061. """
  1062. Populate an 'out' dictionary with mapping names to Python values
  1063. decoded from an 'in' AmpBox mapping strings to string values.
  1064. @param name: the argument name to retrieve
  1065. @type name: C{bytes}
  1066. @param strings: The AmpBox to read string(s) from, a mapping of
  1067. argument names to string values.
  1068. @type strings: AmpBox
  1069. @param objects: The dictionary to write object(s) to, a mapping of
  1070. names to Python objects. Keys will be native strings.
  1071. @type objects: dict
  1072. @param proto: an AMP instance.
  1073. """
  1074. st = self.retrieve(strings, name, proto)
  1075. nk = _wireNameToPythonIdentifier(name)
  1076. if self.optional and st is None:
  1077. objects[nk] = None
  1078. else:
  1079. objects[nk] = self.fromStringProto(st, proto)
  1080. def toBox(self, name, strings, objects, proto):
  1081. """
  1082. Populate an 'out' AmpBox with strings encoded from an 'in' dictionary
  1083. mapping names to Python values.
  1084. @param name: the argument name to retrieve
  1085. @type name: C{bytes}
  1086. @param strings: The AmpBox to write string(s) to, a mapping of
  1087. argument names to string values.
  1088. @type strings: AmpBox
  1089. @param objects: The dictionary to read object(s) from, a mapping of
  1090. names to Python objects. Keys should be native strings.
  1091. @type objects: dict
  1092. @param proto: the protocol we are converting for.
  1093. @type proto: AMP
  1094. """
  1095. obj = self.retrieve(objects, _wireNameToPythonIdentifier(name), proto)
  1096. if self.optional and obj is None:
  1097. # strings[name] = None
  1098. pass
  1099. else:
  1100. strings[name] = self.toStringProto(obj, proto)
  1101. def fromStringProto(self, inString, proto):
  1102. """
  1103. Convert a string to a Python value.
  1104. @param inString: the string to convert.
  1105. @type inString: C{bytes}
  1106. @param proto: the protocol we are converting for.
  1107. @type proto: AMP
  1108. @return: a Python object.
  1109. """
  1110. return self.fromString(inString)
  1111. def toStringProto(self, inObject, proto):
  1112. """
  1113. Convert a Python object to a string.
  1114. @param inObject: the object to convert.
  1115. @param proto: the protocol we are converting for.
  1116. @type proto: AMP
  1117. """
  1118. return self.toString(inObject)
  1119. def fromString(self, inString):
  1120. """
  1121. Convert a string to a Python object. Subclasses must implement this.
  1122. @param inString: the string to convert.
  1123. @type inString: C{bytes}
  1124. @return: the decoded value from C{inString}
  1125. """
  1126. def toString(self, inObject):
  1127. """
  1128. Convert a Python object into a string for passing over the network.
  1129. @param inObject: an object of the type that this Argument is intended
  1130. to deal with.
  1131. @return: the wire encoding of inObject
  1132. @rtype: C{bytes}
  1133. """
  1134. class Integer(Argument):
  1135. """
  1136. Encode any integer values of any size on the wire as the string
  1137. representation.
  1138. Example: C{123} becomes C{"123"}
  1139. """
  1140. fromString = int
  1141. def toString(self, inObject):
  1142. return b"%d" % (inObject,)
  1143. class String(Argument):
  1144. """
  1145. Don't do any conversion at all; just pass through 'str'.
  1146. """
  1147. def toString(self, inObject):
  1148. return inObject
  1149. def fromString(self, inString):
  1150. return inString
  1151. class Float(Argument):
  1152. """
  1153. Encode floating-point values on the wire as their repr.
  1154. """
  1155. fromString = float
  1156. def toString(self, inString):
  1157. if not isinstance(inString, float):
  1158. raise ValueError(f"Bad float value {inString!r}")
  1159. return str(inString).encode("ascii")
  1160. class Boolean(Argument):
  1161. """
  1162. Encode True or False as "True" or "False" on the wire.
  1163. """
  1164. def fromString(self, inString):
  1165. if inString == b"True":
  1166. return True
  1167. elif inString == b"False":
  1168. return False
  1169. else:
  1170. raise TypeError(f"Bad boolean value: {inString!r}")
  1171. def toString(self, inObject):
  1172. if inObject:
  1173. return b"True"
  1174. else:
  1175. return b"False"
  1176. class Unicode(String):
  1177. """
  1178. Encode a unicode string on the wire as UTF-8.
  1179. """
  1180. def toString(self, inObject):
  1181. return String.toString(self, inObject.encode("utf-8"))
  1182. def fromString(self, inString):
  1183. return String.fromString(self, inString).decode("utf-8")
  1184. class Path(Unicode):
  1185. """
  1186. Encode and decode L{filepath.FilePath} instances as paths on the wire.
  1187. This is really intended for use with subprocess communication tools:
  1188. exchanging pathnames on different machines over a network is not generally
  1189. meaningful, but neither is it disallowed; you can use this to communicate
  1190. about NFS paths, for example.
  1191. """
  1192. def fromString(self, inString):
  1193. return filepath.FilePath(Unicode.fromString(self, inString))
  1194. def toString(self, inObject):
  1195. return Unicode.toString(self, inObject.asTextMode().path)
  1196. class ListOf(Argument):
  1197. """
  1198. Encode and decode lists of instances of a single other argument type.
  1199. For example, if you want to pass::
  1200. [3, 7, 9, 15]
  1201. You can create an argument like this::
  1202. ListOf(Integer())
  1203. The serialized form of the entire list is subject to the limit imposed by
  1204. L{MAX_VALUE_LENGTH}. List elements are represented as 16-bit length
  1205. prefixed strings. The argument type passed to the L{ListOf} initializer is
  1206. responsible for producing the serialized form of each element.
  1207. @ivar elementType: The L{Argument} instance used to encode and decode list
  1208. elements (note, not an arbitrary L{IArgumentType} implementation:
  1209. arguments must be implemented using only the C{fromString} and
  1210. C{toString} methods, not the C{fromBox} and C{toBox} methods).
  1211. @param optional: a boolean indicating whether this argument can be
  1212. omitted in the protocol.
  1213. @since: 10.0
  1214. """
  1215. def __init__(self, elementType, optional=False):
  1216. self.elementType = elementType
  1217. Argument.__init__(self, optional)
  1218. def fromString(self, inString):
  1219. """
  1220. Convert the serialized form of a list of instances of some type back
  1221. into that list.
  1222. """
  1223. strings = []
  1224. parser = Int16StringReceiver()
  1225. parser.stringReceived = strings.append
  1226. parser.dataReceived(inString)
  1227. elementFromString = self.elementType.fromString
  1228. return [elementFromString(string) for string in strings]
  1229. def toString(self, inObject):
  1230. """
  1231. Serialize the given list of objects to a single string.
  1232. """
  1233. strings = []
  1234. for obj in inObject:
  1235. serialized = self.elementType.toString(obj)
  1236. strings.append(pack("!H", len(serialized)))
  1237. strings.append(serialized)
  1238. return b"".join(strings)
  1239. class AmpList(Argument):
  1240. """
  1241. Convert a list of dictionaries into a list of AMP boxes on the wire.
  1242. For example, if you want to pass::
  1243. [{'a': 7, 'b': u'hello'}, {'a': 9, 'b': u'goodbye'}]
  1244. You might use an AmpList like this in your arguments or response list::
  1245. AmpList([('a', Integer()),
  1246. ('b', Unicode())])
  1247. """
  1248. def __init__(self, subargs, optional=False):
  1249. """
  1250. Create an AmpList.
  1251. @param subargs: a list of 2-tuples of ('name', argument) describing the
  1252. schema of the dictionaries in the sequence of amp boxes.
  1253. @type subargs: A C{list} of (C{bytes}, L{Argument}) tuples.
  1254. @param optional: a boolean indicating whether this argument can be
  1255. omitted in the protocol.
  1256. """
  1257. assert all(isinstance(name, bytes) for name, _ in subargs), (
  1258. "AmpList should be defined with a list of (name, argument) "
  1259. "tuples where `name' is a byte string, got: %r" % (subargs,)
  1260. )
  1261. self.subargs = subargs
  1262. Argument.__init__(self, optional)
  1263. def fromStringProto(self, inString, proto):
  1264. boxes = parseString(inString)
  1265. values = [_stringsToObjects(box, self.subargs, proto) for box in boxes]
  1266. return values
  1267. def toStringProto(self, inObject, proto):
  1268. return b"".join(
  1269. [
  1270. _objectsToStrings(objects, self.subargs, Box(), proto).serialize()
  1271. for objects in inObject
  1272. ]
  1273. )
  1274. class Descriptor(Integer):
  1275. """
  1276. Encode and decode file descriptors for exchange over a UNIX domain socket.
  1277. This argument type requires an AMP connection set up over an
  1278. L{IUNIXTransport<twisted.internet.interfaces.IUNIXTransport>} provider (for
  1279. example, the kind of connection created by
  1280. L{IReactorUNIX.connectUNIX<twisted.internet.interfaces.IReactorUNIX.connectUNIX>}
  1281. and L{UNIXClientEndpoint<twisted.internet.endpoints.UNIXClientEndpoint>}).
  1282. There is no correspondence between the integer value of the file descriptor
  1283. on the sending and receiving sides, therefore an alternate approach is taken
  1284. to matching up received descriptors with particular L{Descriptor}
  1285. parameters. The argument is encoded to an ordinal (unique per connection)
  1286. for inclusion in the AMP command or response box. The descriptor itself is
  1287. sent using
  1288. L{IUNIXTransport.sendFileDescriptor<twisted.internet.interfaces.IUNIXTransport.sendFileDescriptor>}.
  1289. The receiver uses the order in which file descriptors are received and the
  1290. ordinal value to come up with the received copy of the descriptor.
  1291. """
  1292. def fromStringProto(self, inString, proto):
  1293. """
  1294. Take a unique identifier associated with a file descriptor which must
  1295. have been received by now and use it to look up that descriptor in a
  1296. dictionary where they are kept.
  1297. @param inString: The base representation (as a byte string) of an
  1298. ordinal indicating which file descriptor corresponds to this usage
  1299. of this argument.
  1300. @type inString: C{str}
  1301. @param proto: The protocol used to receive this descriptor. This
  1302. protocol must be connected via a transport providing
  1303. L{IUNIXTransport<twisted.internet.interfaces.IUNIXTransport>}.
  1304. @type proto: L{BinaryBoxProtocol}
  1305. @return: The file descriptor represented by C{inString}.
  1306. @rtype: C{int}
  1307. """
  1308. return proto._getDescriptor(int(inString))
  1309. def toStringProto(self, inObject, proto):
  1310. """
  1311. Send C{inObject}, an integer file descriptor, over C{proto}'s connection
  1312. and return a unique identifier which will allow the receiver to
  1313. associate the file descriptor with this argument.
  1314. @param inObject: A file descriptor to duplicate over an AMP connection
  1315. as the value for this argument.
  1316. @type inObject: C{int}
  1317. @param proto: The protocol which will be used to send this descriptor.
  1318. This protocol must be connected via a transport providing
  1319. L{IUNIXTransport<twisted.internet.interfaces.IUNIXTransport>}.
  1320. @return: A byte string which can be used by the receiver to reconstruct
  1321. the file descriptor.
  1322. @rtype: C{bytes}
  1323. """
  1324. identifier = proto._sendFileDescriptor(inObject)
  1325. outString = Integer.toStringProto(self, identifier, proto)
  1326. return outString
  1327. class _CommandMeta(type):
  1328. """
  1329. Metaclass hack to establish reverse-mappings for 'errors' and
  1330. 'fatalErrors' as class vars.
  1331. """
  1332. def __new__(cls, name, bases, attrs):
  1333. reverseErrors = attrs["reverseErrors"] = {}
  1334. er = attrs["allErrors"] = {}
  1335. if "commandName" not in attrs:
  1336. attrs["commandName"] = name.encode("ascii")
  1337. newtype = type.__new__(cls, name, bases, attrs)
  1338. if not isinstance(newtype.commandName, bytes):
  1339. raise TypeError(
  1340. "Command names must be byte strings, got: {!r}".format(
  1341. newtype.commandName
  1342. )
  1343. )
  1344. for name, _ in newtype.arguments:
  1345. if not isinstance(name, bytes):
  1346. raise TypeError(f"Argument names must be byte strings, got: {name!r}")
  1347. for name, _ in newtype.response:
  1348. if not isinstance(name, bytes):
  1349. raise TypeError(f"Response names must be byte strings, got: {name!r}")
  1350. errors: Dict[Type[Exception], bytes] = {}
  1351. fatalErrors: Dict[Type[Exception], bytes] = {}
  1352. accumulateClassDict(newtype, "errors", errors)
  1353. accumulateClassDict(newtype, "fatalErrors", fatalErrors)
  1354. if not isinstance(newtype.errors, dict):
  1355. newtype.errors = dict(newtype.errors)
  1356. if not isinstance(newtype.fatalErrors, dict):
  1357. newtype.fatalErrors = dict(newtype.fatalErrors)
  1358. for v, k in errors.items():
  1359. reverseErrors[k] = v
  1360. er[v] = k
  1361. for v, k in fatalErrors.items():
  1362. reverseErrors[k] = v
  1363. er[v] = k
  1364. for _, name in newtype.errors.items():
  1365. if not isinstance(name, bytes):
  1366. raise TypeError(f"Error names must be byte strings, got: {name!r}")
  1367. for _, name in newtype.fatalErrors.items():
  1368. if not isinstance(name, bytes):
  1369. raise TypeError(
  1370. f"Fatal error names must be byte strings, got: {name!r}"
  1371. )
  1372. return newtype
  1373. class Command(metaclass=_CommandMeta):
  1374. """
  1375. Subclass me to specify an AMP Command.
  1376. @cvar arguments: A list of 2-tuples of (name, Argument-subclass-instance),
  1377. specifying the names and values of the parameters which are required for
  1378. this command.
  1379. @cvar response: A list like L{arguments}, but instead used for the return
  1380. value.
  1381. @cvar errors: A mapping of subclasses of L{Exception} to wire-protocol tags
  1382. for errors represented as L{str}s. Responders which raise keys from
  1383. this dictionary will have the error translated to the corresponding tag
  1384. on the wire.
  1385. Invokers which receive Deferreds from invoking this command with
  1386. L{BoxDispatcher.callRemote} will potentially receive Failures with keys
  1387. from this mapping as their value.
  1388. This mapping is inherited; if you declare a command which handles
  1389. C{FooError} as 'FOO_ERROR', then subclass it and specify C{BarError} as
  1390. 'BAR_ERROR', responders to the subclass may raise either C{FooError} or
  1391. C{BarError}, and invokers must be able to deal with either of those
  1392. exceptions.
  1393. @cvar fatalErrors: like 'errors', but errors in this list will always
  1394. terminate the connection, despite being of a recognizable error type.
  1395. @cvar commandType: The type of Box used to issue commands; useful only for
  1396. protocol-modifying behavior like startTLS or protocol switching. Defaults
  1397. to a plain vanilla L{Box}.
  1398. @cvar responseType: The type of Box used to respond to this command; only
  1399. useful for protocol-modifying behavior like startTLS or protocol switching.
  1400. Defaults to a plain vanilla L{Box}.
  1401. @ivar requiresAnswer: a boolean; defaults to True. Set it to False on your
  1402. subclass if you want callRemote to return None. Note: this is a hint only
  1403. to the client side of the protocol. The return-type of a command responder
  1404. method must always be a dictionary adhering to the contract specified by
  1405. L{response}, because clients are always free to request a response if they
  1406. want one.
  1407. """
  1408. arguments: List[Tuple[bytes, Argument]] = []
  1409. response: List[Tuple[bytes, Argument]] = []
  1410. extra: List[Any] = []
  1411. errors: Dict[Type[Exception], bytes] = {}
  1412. fatalErrors: Dict[Type[Exception], bytes] = {}
  1413. commandType: "Union[Type[Command], Type[Box]]" = Box
  1414. responseType: Type[AmpBox] = Box
  1415. requiresAnswer = True
  1416. def __init__(self, **kw):
  1417. """
  1418. Create an instance of this command with specified values for its
  1419. parameters.
  1420. In Python 3, keyword arguments MUST be Unicode/native strings whereas
  1421. in Python 2 they could be either byte strings or Unicode strings.
  1422. A L{Command}'s arguments are defined in its schema using C{bytes}
  1423. names. The values for those arguments are plucked from the keyword
  1424. arguments using the name returned from L{_wireNameToPythonIdentifier}.
  1425. In other words, keyword arguments should be named using the
  1426. Python-side equivalent of the on-wire (C{bytes}) name.
  1427. @param kw: a dict containing an appropriate value for each name
  1428. specified in the L{arguments} attribute of my class.
  1429. @raise InvalidSignature: if you forgot any required arguments.
  1430. """
  1431. self.structured = kw
  1432. forgotten = []
  1433. for name, arg in self.arguments:
  1434. pythonName = _wireNameToPythonIdentifier(name)
  1435. if pythonName not in self.structured and not arg.optional:
  1436. forgotten.append(pythonName)
  1437. if forgotten:
  1438. raise InvalidSignature(
  1439. "forgot {} for {}".format(", ".join(forgotten), self.commandName)
  1440. )
  1441. forgotten = []
  1442. @classmethod
  1443. def makeResponse(cls, objects, proto):
  1444. """
  1445. Serialize a mapping of arguments using this L{Command}'s
  1446. response schema.
  1447. @param objects: a dict with keys matching the names specified in
  1448. self.response, having values of the types that the Argument objects in
  1449. self.response can format.
  1450. @param proto: an L{AMP}.
  1451. @return: an L{AmpBox}.
  1452. """
  1453. try:
  1454. responseType = cls.responseType()
  1455. except BaseException:
  1456. return fail()
  1457. return _objectsToStrings(objects, cls.response, responseType, proto)
  1458. @classmethod
  1459. def makeArguments(cls, objects, proto):
  1460. """
  1461. Serialize a mapping of arguments using this L{Command}'s
  1462. argument schema.
  1463. @param objects: a dict with keys similar to the names specified in
  1464. self.arguments, having values of the types that the Argument objects in
  1465. self.arguments can parse.
  1466. @param proto: an L{AMP}.
  1467. @return: An instance of this L{Command}'s C{commandType}.
  1468. """
  1469. allowedNames = set()
  1470. for (argName, ignored) in cls.arguments:
  1471. allowedNames.add(_wireNameToPythonIdentifier(argName))
  1472. for intendedArg in objects:
  1473. if intendedArg not in allowedNames:
  1474. raise InvalidSignature(f"{intendedArg} is not a valid argument")
  1475. return _objectsToStrings(objects, cls.arguments, cls.commandType(), proto)
  1476. @classmethod
  1477. def parseResponse(cls, box, protocol):
  1478. """
  1479. Parse a mapping of serialized arguments using this
  1480. L{Command}'s response schema.
  1481. @param box: A mapping of response-argument names to the
  1482. serialized forms of those arguments.
  1483. @param protocol: The L{AMP} protocol.
  1484. @return: A mapping of response-argument names to the parsed
  1485. forms.
  1486. """
  1487. return _stringsToObjects(box, cls.response, protocol)
  1488. @classmethod
  1489. def parseArguments(cls, box, protocol):
  1490. """
  1491. Parse a mapping of serialized arguments using this
  1492. L{Command}'s argument schema.
  1493. @param box: A mapping of argument names to the seralized forms
  1494. of those arguments.
  1495. @param protocol: The L{AMP} protocol.
  1496. @return: A mapping of argument names to the parsed forms.
  1497. """
  1498. return _stringsToObjects(box, cls.arguments, protocol)
  1499. @classmethod
  1500. def responder(cls, methodfunc):
  1501. """
  1502. Declare a method to be a responder for a particular command.
  1503. This is a decorator.
  1504. Use like so::
  1505. class MyCommand(Command):
  1506. arguments = [('a', ...), ('b', ...)]
  1507. class MyProto(AMP):
  1508. def myFunMethod(self, a, b):
  1509. ...
  1510. MyCommand.responder(myFunMethod)
  1511. Notes: Although decorator syntax is not used within Twisted, this
  1512. function returns its argument and is therefore safe to use with
  1513. decorator syntax.
  1514. This is not thread safe. Don't declare AMP subclasses in other
  1515. threads. Don't declare responders outside the scope of AMP subclasses;
  1516. the behavior is undefined.
  1517. @param methodfunc: A function which will later become a method, which
  1518. has a keyword signature compatible with this command's L{arguments} list
  1519. and returns a dictionary with a set of keys compatible with this
  1520. command's L{response} list.
  1521. @return: the methodfunc parameter.
  1522. """
  1523. CommandLocator._currentClassCommands.append((cls, methodfunc))
  1524. return methodfunc
  1525. # Our only instance method
  1526. def _doCommand(self, proto):
  1527. """
  1528. Encode and send this Command to the given protocol.
  1529. @param proto: an AMP, representing the connection to send to.
  1530. @return: a Deferred which will fire or error appropriately when the
  1531. other side responds to the command (or error if the connection is lost
  1532. before it is responded to).
  1533. """
  1534. def _massageError(error):
  1535. error.trap(RemoteAmpError)
  1536. rje = error.value
  1537. errorType = self.reverseErrors.get(rje.errorCode, UnknownRemoteError)
  1538. return Failure(errorType(rje.description))
  1539. d = proto._sendBoxCommand(
  1540. self.commandName,
  1541. self.makeArguments(self.structured, proto),
  1542. self.requiresAnswer,
  1543. )
  1544. if self.requiresAnswer:
  1545. d.addCallback(self.parseResponse, proto)
  1546. d.addErrback(_massageError)
  1547. return d
  1548. class _NoCertificate:
  1549. """
  1550. This is for peers which don't want to use a local certificate. Used by
  1551. AMP because AMP's internal language is all about certificates and this
  1552. duck-types in the appropriate place; this API isn't really stable though,
  1553. so it's not exposed anywhere public.
  1554. For clients, it will use ephemeral DH keys, or whatever the default is for
  1555. certificate-less clients in OpenSSL. For servers, it will generate a
  1556. temporary self-signed certificate with garbage values in the DN and use
  1557. that.
  1558. """
  1559. def __init__(self, client):
  1560. """
  1561. Create a _NoCertificate which either is or isn't for the client side of
  1562. the connection.
  1563. @param client: True if we are a client and should truly have no
  1564. certificate and be anonymous, False if we are a server and actually
  1565. have to generate a temporary certificate.
  1566. @type client: bool
  1567. """
  1568. self.client = client
  1569. def options(self, *authorities):
  1570. """
  1571. Behaves like L{twisted.internet.ssl.PrivateCertificate.options}().
  1572. """
  1573. if not self.client:
  1574. # do some crud with sslverify to generate a temporary self-signed
  1575. # certificate. This is SLOOOWWWWW so it is only in the absolute
  1576. # worst, most naive case.
  1577. # We have to do this because OpenSSL will not let both the server
  1578. # and client be anonymous.
  1579. sharedDN = DN(CN="TEMPORARY CERTIFICATE")
  1580. key = KeyPair.generate()
  1581. cr = key.certificateRequest(sharedDN)
  1582. sscrd = key.signCertificateRequest(sharedDN, cr, lambda dn: True, 1)
  1583. cert = key.newCertificate(sscrd)
  1584. return cert.options(*authorities)
  1585. options = dict()
  1586. if authorities:
  1587. options.update(
  1588. dict(
  1589. verify=True,
  1590. requireCertificate=True,
  1591. caCerts=[auth.original for auth in authorities],
  1592. )
  1593. )
  1594. occo = CertificateOptions(**options)
  1595. return occo
  1596. class _TLSBox(AmpBox):
  1597. """
  1598. I am an AmpBox that, upon being sent, initiates a TLS connection.
  1599. """
  1600. __slots__: List[str] = []
  1601. def __init__(self):
  1602. if ssl is None:
  1603. raise RemoteAmpError(b"TLS_ERROR", "TLS not available")
  1604. AmpBox.__init__(self)
  1605. @property
  1606. def certificate(self):
  1607. return self.get(b"tls_localCertificate", _NoCertificate(False))
  1608. @property
  1609. def verify(self):
  1610. return self.get(b"tls_verifyAuthorities", None)
  1611. def _sendTo(self, proto):
  1612. """
  1613. Send my encoded value to the protocol, then initiate TLS.
  1614. """
  1615. ab = AmpBox(self)
  1616. for k in [b"tls_localCertificate", b"tls_verifyAuthorities"]:
  1617. ab.pop(k, None)
  1618. ab._sendTo(proto)
  1619. proto._startTLS(self.certificate, self.verify)
  1620. class _LocalArgument(String):
  1621. """
  1622. Local arguments are never actually relayed across the wire. This is just a
  1623. shim so that StartTLS can pretend to have some arguments: if arguments
  1624. acquire documentation properties, replace this with something nicer later.
  1625. """
  1626. def fromBox(self, name, strings, objects, proto):
  1627. pass
  1628. class StartTLS(Command):
  1629. """
  1630. Use, or subclass, me to implement a command that starts TLS.
  1631. Callers of StartTLS may pass several special arguments, which affect the
  1632. TLS negotiation:
  1633. - tls_localCertificate: This is a
  1634. twisted.internet.ssl.PrivateCertificate which will be used to secure
  1635. the side of the connection it is returned on.
  1636. - tls_verifyAuthorities: This is a list of
  1637. twisted.internet.ssl.Certificate objects that will be used as the
  1638. certificate authorities to verify our peer's certificate.
  1639. Each of those special parameters may also be present as a key in the
  1640. response dictionary.
  1641. """
  1642. arguments = [
  1643. (b"tls_localCertificate", _LocalArgument(optional=True)),
  1644. (b"tls_verifyAuthorities", _LocalArgument(optional=True)),
  1645. ]
  1646. response = [
  1647. (b"tls_localCertificate", _LocalArgument(optional=True)),
  1648. (b"tls_verifyAuthorities", _LocalArgument(optional=True)),
  1649. ]
  1650. responseType = _TLSBox
  1651. def __init__(self, *, tls_localCertificate=None, tls_verifyAuthorities=None, **kw):
  1652. """
  1653. Create a StartTLS command. (This is private. Use AMP.callRemote.)
  1654. @param tls_localCertificate: the PrivateCertificate object to use to
  1655. secure the connection. If it's L{None}, or unspecified, an ephemeral DH
  1656. key is used instead.
  1657. @param tls_verifyAuthorities: a list of Certificate objects which
  1658. represent root certificates to verify our peer with.
  1659. """
  1660. if ssl is None:
  1661. raise RuntimeError("TLS not available.")
  1662. self.certificate = (
  1663. _NoCertificate(True)
  1664. if tls_localCertificate is None
  1665. else tls_localCertificate
  1666. )
  1667. self.authorities = tls_verifyAuthorities
  1668. Command.__init__(self, **kw)
  1669. def _doCommand(self, proto):
  1670. """
  1671. When a StartTLS command is sent, prepare to start TLS, but don't actually
  1672. do it; wait for the acknowledgement, then initiate the TLS handshake.
  1673. """
  1674. d = Command._doCommand(self, proto)
  1675. proto._prepareTLS(self.certificate, self.authorities)
  1676. # XXX before we get back to user code we are going to start TLS...
  1677. def actuallystart(response):
  1678. proto._startTLS(self.certificate, self.authorities)
  1679. return response
  1680. d.addCallback(actuallystart)
  1681. return d
  1682. class ProtocolSwitchCommand(Command):
  1683. """
  1684. Use this command to switch from something Amp-derived to a different
  1685. protocol mid-connection. This can be useful to use amp as the
  1686. connection-startup negotiation phase. Since TLS is a different layer
  1687. entirely, you can use Amp to negotiate the security parameters of your
  1688. connection, then switch to a different protocol, and the connection will
  1689. remain secured.
  1690. """
  1691. def __init__(self, _protoToSwitchToFactory, **kw):
  1692. """
  1693. Create a ProtocolSwitchCommand.
  1694. @param _protoToSwitchToFactory: a ProtocolFactory which will generate
  1695. the Protocol to switch to.
  1696. @param kw: Keyword arguments, encoded and handled normally as
  1697. L{Command} would.
  1698. """
  1699. self.protoToSwitchToFactory = _protoToSwitchToFactory
  1700. super().__init__(**kw)
  1701. @classmethod
  1702. def makeResponse(cls, innerProto, proto):
  1703. return _SwitchBox(innerProto)
  1704. def _doCommand(self, proto):
  1705. """
  1706. When we emit a ProtocolSwitchCommand, lock the protocol, but don't actually
  1707. switch to the new protocol unless an acknowledgement is received. If
  1708. an error is received, switch back.
  1709. """
  1710. d = super()._doCommand(proto)
  1711. proto._lockForSwitch()
  1712. def switchNow(ign):
  1713. innerProto = self.protoToSwitchToFactory.buildProtocol(
  1714. proto.transport.getPeer()
  1715. )
  1716. proto._switchTo(innerProto, self.protoToSwitchToFactory)
  1717. return ign
  1718. def handle(ign):
  1719. proto._unlockFromSwitch()
  1720. self.protoToSwitchToFactory.clientConnectionFailed(
  1721. None, Failure(CONNECTION_LOST)
  1722. )
  1723. return ign
  1724. return d.addCallbacks(switchNow, handle)
  1725. @implementer(IFileDescriptorReceiver)
  1726. class _DescriptorExchanger:
  1727. """
  1728. L{_DescriptorExchanger} is a mixin for L{BinaryBoxProtocol} which adds
  1729. support for receiving file descriptors, a feature offered by
  1730. L{IUNIXTransport<twisted.internet.interfaces.IUNIXTransport>}.
  1731. @ivar _descriptors: Temporary storage for all file descriptors received.
  1732. Values in this dictionary are the file descriptors (as integers). Keys
  1733. in this dictionary are ordinals giving the order in which each
  1734. descriptor was received. The ordering information is used to allow
  1735. L{Descriptor} to determine which is the correct descriptor for any
  1736. particular usage of that argument type.
  1737. @type _descriptors: C{dict}
  1738. @ivar _sendingDescriptorCounter: A no-argument callable which returns the
  1739. ordinals, starting from 0. This is used to construct values for
  1740. C{_sendFileDescriptor}.
  1741. @ivar _receivingDescriptorCounter: A no-argument callable which returns the
  1742. ordinals, starting from 0. This is used to construct values for
  1743. C{fileDescriptorReceived}.
  1744. """
  1745. def __init__(self):
  1746. self._descriptors = {}
  1747. self._getDescriptor = self._descriptors.pop
  1748. self._sendingDescriptorCounter = partial(next, count())
  1749. self._receivingDescriptorCounter = partial(next, count())
  1750. def _sendFileDescriptor(self, descriptor):
  1751. """
  1752. Assign and return the next ordinal to the given descriptor after sending
  1753. the descriptor over this protocol's transport.
  1754. """
  1755. self.transport.sendFileDescriptor(descriptor)
  1756. return self._sendingDescriptorCounter()
  1757. def fileDescriptorReceived(self, descriptor):
  1758. """
  1759. Collect received file descriptors to be claimed later by L{Descriptor}.
  1760. @param descriptor: The received file descriptor.
  1761. @type descriptor: C{int}
  1762. """
  1763. self._descriptors[self._receivingDescriptorCounter()] = descriptor
  1764. @implementer(IBoxSender)
  1765. class BinaryBoxProtocol(
  1766. StatefulStringProtocol, Int16StringReceiver, _DescriptorExchanger
  1767. ):
  1768. """
  1769. A protocol for receiving L{AmpBox}es - key/value pairs - via length-prefixed
  1770. strings. A box is composed of:
  1771. - any number of key-value pairs, described by:
  1772. - a 2-byte network-endian packed key length (of which the first
  1773. byte must be null, and the second must be non-null: i.e. the
  1774. value of the length must be 1-255)
  1775. - a key, comprised of that many bytes
  1776. - a 2-byte network-endian unsigned value length (up to the maximum
  1777. of 65535)
  1778. - a value, comprised of that many bytes
  1779. - 2 null bytes
  1780. In other words, an even number of strings prefixed with packed unsigned
  1781. 16-bit integers, and then a 0-length string to indicate the end of the box.
  1782. This protocol also implements 2 extra private bits of functionality related
  1783. to the byte boundaries between messages; it can start TLS between two given
  1784. boxes or switch to an entirely different protocol. However, due to some
  1785. tricky elements of the implementation, the public interface to this
  1786. functionality is L{ProtocolSwitchCommand} and L{StartTLS}.
  1787. @ivar _keyLengthLimitExceeded: A flag which is only true when the
  1788. connection is being closed because a key length prefix which was longer
  1789. than allowed by the protocol was received.
  1790. @ivar boxReceiver: an L{IBoxReceiver} provider, whose
  1791. L{IBoxReceiver.ampBoxReceived} method will be invoked for each
  1792. L{AmpBox} that is received.
  1793. """
  1794. _justStartedTLS = False
  1795. _startingTLSBuffer = None
  1796. _locked = False
  1797. _currentKey = None
  1798. _currentBox = None
  1799. _keyLengthLimitExceeded = False
  1800. hostCertificate = None
  1801. noPeerCertificate = False # for tests
  1802. innerProtocol: Optional[Protocol] = None
  1803. innerProtocolClientFactory = None
  1804. def __init__(self, boxReceiver):
  1805. _DescriptorExchanger.__init__(self)
  1806. self.boxReceiver = boxReceiver
  1807. def _switchTo(self, newProto, clientFactory=None):
  1808. """
  1809. Switch this BinaryBoxProtocol's transport to a new protocol. You need
  1810. to do this 'simultaneously' on both ends of a connection; the easiest
  1811. way to do this is to use a subclass of ProtocolSwitchCommand.
  1812. @param newProto: the new protocol instance to switch to.
  1813. @param clientFactory: the ClientFactory to send the
  1814. L{twisted.internet.protocol.ClientFactory.clientConnectionLost}
  1815. notification to.
  1816. """
  1817. # All the data that Int16Receiver has not yet dealt with belongs to our
  1818. # new protocol: luckily it's keeping that in a handy (although
  1819. # ostensibly internal) variable for us:
  1820. newProtoData = self.recvd
  1821. # We're quite possibly in the middle of a 'dataReceived' loop in
  1822. # Int16StringReceiver: let's make sure that the next iteration, the
  1823. # loop will break and not attempt to look at something that isn't a
  1824. # length prefix.
  1825. self.recvd = ""
  1826. # Finally, do the actual work of setting up the protocol and delivering
  1827. # its first chunk of data, if one is available.
  1828. self.innerProtocol = newProto
  1829. self.innerProtocolClientFactory = clientFactory
  1830. newProto.makeConnection(self.transport)
  1831. if newProtoData:
  1832. newProto.dataReceived(newProtoData)
  1833. def sendBox(self, box):
  1834. """
  1835. Send a amp.Box to my peer.
  1836. Note: transport.write is never called outside of this method.
  1837. @param box: an AmpBox.
  1838. @raise ProtocolSwitched: if the protocol has previously been switched.
  1839. @raise ConnectionLost: if the connection has previously been lost.
  1840. """
  1841. if self._locked:
  1842. raise ProtocolSwitched(
  1843. "This connection has switched: no AMP traffic allowed."
  1844. )
  1845. if self.transport is None:
  1846. raise ConnectionLost()
  1847. if self._startingTLSBuffer is not None:
  1848. self._startingTLSBuffer.append(box)
  1849. else:
  1850. self.transport.write(box.serialize())
  1851. def makeConnection(self, transport):
  1852. """
  1853. Notify L{boxReceiver} that it is about to receive boxes from this
  1854. protocol by invoking L{IBoxReceiver.startReceivingBoxes}.
  1855. """
  1856. self.transport = transport
  1857. self.boxReceiver.startReceivingBoxes(self)
  1858. self.connectionMade()
  1859. def dataReceived(self, data):
  1860. """
  1861. Either parse incoming data as L{AmpBox}es or relay it to our nested
  1862. protocol.
  1863. """
  1864. if self._justStartedTLS:
  1865. self._justStartedTLS = False
  1866. # If we already have an inner protocol, then we don't deliver data to
  1867. # the protocol parser any more; we just hand it off.
  1868. if self.innerProtocol is not None:
  1869. self.innerProtocol.dataReceived(data)
  1870. return
  1871. return Int16StringReceiver.dataReceived(self, data)
  1872. def connectionLost(self, reason):
  1873. """
  1874. The connection was lost; notify any nested protocol.
  1875. """
  1876. if self.innerProtocol is not None:
  1877. self.innerProtocol.connectionLost(reason)
  1878. if self.innerProtocolClientFactory is not None:
  1879. self.innerProtocolClientFactory.clientConnectionLost(None, reason)
  1880. if self._keyLengthLimitExceeded:
  1881. failReason = Failure(TooLong(True, False, None, None))
  1882. elif reason.check(ConnectionClosed) and self._justStartedTLS:
  1883. # We just started TLS and haven't received any data. This means
  1884. # the other connection didn't like our cert (although they may not
  1885. # have told us why - later Twisted should make 'reason' into a TLS
  1886. # error.)
  1887. failReason = PeerVerifyError(
  1888. "Peer rejected our certificate for an unknown reason."
  1889. )
  1890. else:
  1891. failReason = reason
  1892. self.boxReceiver.stopReceivingBoxes(failReason)
  1893. # The longest key allowed
  1894. _MAX_KEY_LENGTH = 255
  1895. # The longest value allowed (this is somewhat redundant, as longer values
  1896. # cannot be encoded - ah well).
  1897. _MAX_VALUE_LENGTH = 65535
  1898. # The first thing received is a key.
  1899. MAX_LENGTH = _MAX_KEY_LENGTH
  1900. def proto_init(self, string):
  1901. """
  1902. String received in the 'init' state.
  1903. """
  1904. self._currentBox = AmpBox()
  1905. return self.proto_key(string)
  1906. def proto_key(self, string):
  1907. """
  1908. String received in the 'key' state. If the key is empty, a complete
  1909. box has been received.
  1910. """
  1911. if string:
  1912. self._currentKey = string
  1913. self.MAX_LENGTH = self._MAX_VALUE_LENGTH
  1914. return "value"
  1915. else:
  1916. self.boxReceiver.ampBoxReceived(self._currentBox)
  1917. self._currentBox = None
  1918. return "init"
  1919. def proto_value(self, string):
  1920. """
  1921. String received in the 'value' state.
  1922. """
  1923. self._currentBox[self._currentKey] = string
  1924. self._currentKey = None
  1925. self.MAX_LENGTH = self._MAX_KEY_LENGTH
  1926. return "key"
  1927. def lengthLimitExceeded(self, length):
  1928. """
  1929. The key length limit was exceeded. Disconnect the transport and make
  1930. sure a meaningful exception is reported.
  1931. """
  1932. self._keyLengthLimitExceeded = True
  1933. self.transport.loseConnection()
  1934. def _lockForSwitch(self):
  1935. """
  1936. Lock this binary protocol so that no further boxes may be sent. This
  1937. is used when sending a request to switch underlying protocols. You
  1938. probably want to subclass ProtocolSwitchCommand rather than calling
  1939. this directly.
  1940. """
  1941. self._locked = True
  1942. def _unlockFromSwitch(self):
  1943. """
  1944. Unlock this locked binary protocol so that further boxes may be sent
  1945. again. This is used after an attempt to switch protocols has failed
  1946. for some reason.
  1947. """
  1948. if self.innerProtocol is not None:
  1949. raise ProtocolSwitched("Protocol already switched. Cannot unlock.")
  1950. self._locked = False
  1951. def _prepareTLS(self, certificate, verifyAuthorities):
  1952. """
  1953. Used by StartTLSCommand to put us into the state where we don't
  1954. actually send things that get sent, instead we buffer them. see
  1955. L{_sendBoxCommand}.
  1956. """
  1957. self._startingTLSBuffer = []
  1958. if self.hostCertificate is not None:
  1959. raise OnlyOneTLS(
  1960. "Previously authenticated connection between %s and %s "
  1961. "is trying to re-establish as %s"
  1962. % (
  1963. self.hostCertificate,
  1964. self.peerCertificate,
  1965. (certificate, verifyAuthorities),
  1966. )
  1967. )
  1968. def _startTLS(self, certificate, verifyAuthorities):
  1969. """
  1970. Used by TLSBox to initiate the SSL handshake.
  1971. @param certificate: a L{twisted.internet.ssl.PrivateCertificate} for
  1972. use locally.
  1973. @param verifyAuthorities: L{twisted.internet.ssl.Certificate} instances
  1974. representing certificate authorities which will verify our peer.
  1975. """
  1976. self.hostCertificate = certificate
  1977. self._justStartedTLS = True
  1978. if verifyAuthorities is None:
  1979. verifyAuthorities = ()
  1980. self.transport.startTLS(certificate.options(*verifyAuthorities))
  1981. stlsb = self._startingTLSBuffer
  1982. if stlsb is not None:
  1983. self._startingTLSBuffer = None
  1984. for box in stlsb:
  1985. self.sendBox(box)
  1986. @property
  1987. def peerCertificate(self):
  1988. if self.noPeerCertificate:
  1989. return None
  1990. return Certificate.peerFromTransport(self.transport)
  1991. def unhandledError(self, failure):
  1992. """
  1993. The buck stops here. This error was completely unhandled, time to
  1994. terminate the connection.
  1995. """
  1996. log.err(
  1997. failure,
  1998. "Amp server or network failure unhandled by client application. "
  1999. "Dropping connection! To avoid, add errbacks to ALL remote "
  2000. "commands!",
  2001. )
  2002. if self.transport is not None:
  2003. self.transport.loseConnection()
  2004. def _defaultStartTLSResponder(self):
  2005. """
  2006. The default TLS responder doesn't specify any certificate or anything.
  2007. From a security perspective, it's little better than a plain-text
  2008. connection - but it is still a *bit* better, so it's included for
  2009. convenience.
  2010. You probably want to override this by providing your own StartTLS.responder.
  2011. """
  2012. return {}
  2013. StartTLS.responder(_defaultStartTLSResponder)
  2014. class AMP(BinaryBoxProtocol, BoxDispatcher, CommandLocator, SimpleStringLocator):
  2015. """
  2016. This protocol is an AMP connection. See the module docstring for protocol
  2017. details.
  2018. """
  2019. _ampInitialized = False
  2020. def __init__(self, boxReceiver=None, locator=None):
  2021. # For backwards compatibility. When AMP did not separate parsing logic
  2022. # (L{BinaryBoxProtocol}), request-response logic (L{BoxDispatcher}) and
  2023. # command routing (L{CommandLocator}), it did not have a constructor.
  2024. # Now it does, so old subclasses might have defined their own that did
  2025. # not upcall. If this flag isn't set, we'll call the constructor in
  2026. # makeConnection before anything actually happens.
  2027. self._ampInitialized = True
  2028. if boxReceiver is None:
  2029. boxReceiver = self
  2030. if locator is None:
  2031. locator = self
  2032. BoxDispatcher.__init__(self, locator)
  2033. BinaryBoxProtocol.__init__(self, boxReceiver)
  2034. def locateResponder(self, name):
  2035. """
  2036. Unify the implementations of L{CommandLocator} and
  2037. L{SimpleStringLocator} to perform both kinds of dispatch, preferring
  2038. L{CommandLocator}.
  2039. @type name: C{bytes}
  2040. """
  2041. firstResponder = CommandLocator.locateResponder(self, name)
  2042. if firstResponder is not None:
  2043. return firstResponder
  2044. secondResponder = SimpleStringLocator.locateResponder(self, name)
  2045. return secondResponder
  2046. def __repr__(self) -> str:
  2047. """
  2048. A verbose string representation which gives us information about this
  2049. AMP connection.
  2050. """
  2051. if self.innerProtocol is not None:
  2052. innerRepr = f" inner {self.innerProtocol!r}"
  2053. else:
  2054. innerRepr = ""
  2055. return f"<{self.__class__.__name__}{innerRepr} at 0x{id(self):x}>"
  2056. def makeConnection(self, transport):
  2057. """
  2058. Emit a helpful log message when the connection is made.
  2059. """
  2060. if not self._ampInitialized:
  2061. # See comment in the constructor re: backward compatibility. I
  2062. # should probably emit a deprecation warning here.
  2063. AMP.__init__(self)
  2064. # Save these so we can emit a similar log message in L{connectionLost}.
  2065. self._transportPeer = transport.getPeer()
  2066. self._transportHost = transport.getHost()
  2067. log.msg(
  2068. "%s connection established (HOST:%s PEER:%s)"
  2069. % (self.__class__.__name__, self._transportHost, self._transportPeer)
  2070. )
  2071. BinaryBoxProtocol.makeConnection(self, transport)
  2072. def connectionLost(self, reason):
  2073. """
  2074. Emit a helpful log message when the connection is lost.
  2075. """
  2076. log.msg(
  2077. "%s connection lost (HOST:%s PEER:%s)"
  2078. % (self.__class__.__name__, self._transportHost, self._transportPeer)
  2079. )
  2080. BinaryBoxProtocol.connectionLost(self, reason)
  2081. self.transport = None
  2082. class _ParserHelper:
  2083. """
  2084. A box receiver which records all boxes received.
  2085. """
  2086. def __init__(self):
  2087. self.boxes = []
  2088. def getPeer(self):
  2089. return "string"
  2090. def getHost(self):
  2091. return "string"
  2092. disconnecting = False
  2093. def startReceivingBoxes(self, sender):
  2094. """
  2095. No initialization is required.
  2096. """
  2097. def ampBoxReceived(self, box):
  2098. self.boxes.append(box)
  2099. # Synchronous helpers
  2100. @classmethod
  2101. def parse(cls, fileObj):
  2102. """
  2103. Parse some amp data stored in a file.
  2104. @param fileObj: a file-like object.
  2105. @return: a list of AmpBoxes encoded in the given file.
  2106. """
  2107. parserHelper = cls()
  2108. bbp = BinaryBoxProtocol(boxReceiver=parserHelper)
  2109. bbp.makeConnection(parserHelper)
  2110. bbp.dataReceived(fileObj.read())
  2111. return parserHelper.boxes
  2112. @classmethod
  2113. def parseString(cls, data):
  2114. """
  2115. Parse some amp data stored in a string.
  2116. @param data: a str holding some amp-encoded data.
  2117. @return: a list of AmpBoxes encoded in the given string.
  2118. """
  2119. return cls.parse(BytesIO(data))
  2120. parse = _ParserHelper.parse
  2121. parseString = _ParserHelper.parseString
  2122. def _stringsToObjects(strings, arglist, proto):
  2123. """
  2124. Convert an AmpBox to a dictionary of python objects, converting through a
  2125. given arglist.
  2126. @param strings: an AmpBox (or dict of strings)
  2127. @param arglist: a list of 2-tuples of strings and Argument objects, as
  2128. described in L{Command.arguments}.
  2129. @param proto: an L{AMP} instance.
  2130. @return: the converted dictionary mapping names to argument objects.
  2131. """
  2132. objects = {}
  2133. myStrings = strings.copy()
  2134. for argname, argparser in arglist:
  2135. argparser.fromBox(argname, myStrings, objects, proto)
  2136. return objects
  2137. def _objectsToStrings(objects, arglist, strings, proto):
  2138. """
  2139. Convert a dictionary of python objects to an AmpBox, converting through a
  2140. given arglist.
  2141. @param objects: a dict mapping names to python objects
  2142. @param arglist: a list of 2-tuples of strings and Argument objects, as
  2143. described in L{Command.arguments}.
  2144. @param strings: [OUT PARAMETER] An object providing the L{dict}
  2145. interface which will be populated with serialized data.
  2146. @param proto: an L{AMP} instance.
  2147. @return: The converted dictionary mapping names to encoded argument
  2148. strings (identical to C{strings}).
  2149. """
  2150. myObjects = objects.copy()
  2151. for argname, argparser in arglist:
  2152. argparser.toBox(argname, strings, myObjects, proto)
  2153. return strings
  2154. class Decimal(Argument):
  2155. """
  2156. Encodes C{decimal.Decimal} instances.
  2157. There are several ways in which a decimal value might be encoded.
  2158. Special values are encoded as special strings::
  2159. - Positive infinity is encoded as C{"Infinity"}
  2160. - Negative infinity is encoded as C{"-Infinity"}
  2161. - Quiet not-a-number is encoded as either C{"NaN"} or C{"-NaN"}
  2162. - Signalling not-a-number is encoded as either C{"sNaN"} or C{"-sNaN"}
  2163. Normal values are encoded using the base ten string representation, using
  2164. engineering notation to indicate magnitude without precision, and "normal"
  2165. digits to indicate precision. For example::
  2166. - C{"1"} represents the value I{1} with precision to one place.
  2167. - C{"-1"} represents the value I{-1} with precision to one place.
  2168. - C{"1.0"} represents the value I{1} with precision to two places.
  2169. - C{"10"} represents the value I{10} with precision to two places.
  2170. - C{"1E+2"} represents the value I{10} with precision to one place.
  2171. - C{"1E-1"} represents the value I{0.1} with precision to one place.
  2172. - C{"1.5E+2"} represents the value I{15} with precision to two places.
  2173. U{http://speleotrove.com/decimal/} should be considered the authoritative
  2174. specification for the format.
  2175. """
  2176. def fromString(self, inString):
  2177. inString = nativeString(inString)
  2178. return decimal.Decimal(inString)
  2179. def toString(self, inObject):
  2180. """
  2181. Serialize a C{decimal.Decimal} instance to the specified wire format.
  2182. """
  2183. if isinstance(inObject, decimal.Decimal):
  2184. # Hopefully decimal.Decimal.__str__ actually does what we want.
  2185. return str(inObject).encode("ascii")
  2186. raise ValueError("amp.Decimal can only encode instances of decimal.Decimal")
  2187. class DateTime(Argument):
  2188. """
  2189. Encodes C{datetime.datetime} instances.
  2190. Wire format: '%04i-%02i-%02iT%02i:%02i:%02i.%06i%s%02i:%02i'. Fields in
  2191. order are: year, month, day, hour, minute, second, microsecond, timezone
  2192. direction (+ or -), timezone hour, timezone minute. Encoded string is
  2193. always exactly 32 characters long. This format is compatible with ISO 8601,
  2194. but that does not mean all ISO 8601 dates can be accepted.
  2195. Also, note that the datetime module's notion of a "timezone" can be
  2196. complex, but the wire format includes only a fixed offset, so the
  2197. conversion is not lossless. A lossless transmission of a C{datetime} instance
  2198. is not feasible since the receiving end would require a Python interpreter.
  2199. @ivar _positions: A sequence of slices giving the positions of various
  2200. interesting parts of the wire format.
  2201. """
  2202. _positions = [
  2203. slice(0, 4),
  2204. slice(5, 7),
  2205. slice(8, 10), # year, month, day
  2206. slice(11, 13),
  2207. slice(14, 16),
  2208. slice(17, 19), # hour, minute, second
  2209. slice(20, 26), # microsecond
  2210. # intentionally skip timezone direction, as it is not an integer
  2211. slice(27, 29),
  2212. slice(30, 32), # timezone hour, timezone minute
  2213. ]
  2214. def fromString(self, s):
  2215. """
  2216. Parse a string containing a date and time in the wire format into a
  2217. C{datetime.datetime} instance.
  2218. """
  2219. s = nativeString(s)
  2220. if len(s) != 32:
  2221. raise ValueError(f"invalid date format {s!r}")
  2222. values = [int(s[p]) for p in self._positions]
  2223. sign = s[26]
  2224. timezone = _FixedOffsetTZInfo.fromSignHoursMinutes(sign, *values[7:])
  2225. values[7:] = [timezone]
  2226. return datetime.datetime(*values)
  2227. def toString(self, i):
  2228. """
  2229. Serialize a C{datetime.datetime} instance to a string in the specified
  2230. wire format.
  2231. """
  2232. offset = i.utcoffset()
  2233. if offset is None:
  2234. raise ValueError(
  2235. "amp.DateTime cannot serialize naive datetime instances. "
  2236. "You may find amp.utc useful."
  2237. )
  2238. minutesOffset = (offset.days * 86400 + offset.seconds) // 60
  2239. if minutesOffset > 0:
  2240. sign = "+"
  2241. else:
  2242. sign = "-"
  2243. # strftime has no way to format the microseconds, or put a ':' in the
  2244. # timezone. Surprise!
  2245. # Python 3.4 cannot do % interpolation on byte strings so we pack into
  2246. # an explicitly Unicode string then encode as ASCII.
  2247. packed = "%04i-%02i-%02iT%02i:%02i:%02i.%06i%s%02i:%02i" % (
  2248. i.year,
  2249. i.month,
  2250. i.day,
  2251. i.hour,
  2252. i.minute,
  2253. i.second,
  2254. i.microsecond,
  2255. sign,
  2256. abs(minutesOffset) // 60,
  2257. abs(minutesOffset) % 60,
  2258. )
  2259. return packed.encode("ascii")