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.

banana.py 12KB

1 year ago
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403
  1. # -*- test-case-name: twisted.spread.test.test_banana -*-
  2. # Copyright (c) Twisted Matrix Laboratories.
  3. # See LICENSE for details.
  4. """
  5. Banana -- s-exp based protocol.
  6. Future Plans: This module is almost entirely stable. The same caveat applies
  7. to it as applies to L{twisted.spread.jelly}, however. Read its future plans
  8. for more details.
  9. @author: Glyph Lefkowitz
  10. """
  11. import copy
  12. import struct
  13. from io import BytesIO
  14. from twisted.internet import protocol
  15. from twisted.persisted import styles
  16. from twisted.python import log
  17. from twisted.python.compat import iterbytes
  18. from twisted.python.reflect import fullyQualifiedName
  19. class BananaError(Exception):
  20. pass
  21. def int2b128(integer, stream):
  22. if integer == 0:
  23. stream(b"\0")
  24. return
  25. assert integer > 0, "can only encode positive integers"
  26. while integer:
  27. stream(bytes((integer & 0x7F,)))
  28. integer = integer >> 7
  29. def b1282int(st):
  30. """
  31. Convert an integer represented as a base 128 string into an L{int}.
  32. @param st: The integer encoded in a byte string.
  33. @type st: L{bytes}
  34. @return: The integer value extracted from the byte string.
  35. @rtype: L{int}
  36. """
  37. e = 1
  38. i = 0
  39. for char in iterbytes(st):
  40. n = ord(char)
  41. i += n * e
  42. e <<= 7
  43. return i
  44. # delimiter characters.
  45. LIST = b"\x80"
  46. INT = b"\x81"
  47. STRING = b"\x82"
  48. NEG = b"\x83"
  49. FLOAT = b"\x84"
  50. # "optional" -- these might be refused by a low-level implementation.
  51. LONGINT = b"\x85"
  52. LONGNEG = b"\x86"
  53. # really optional; this is part of the 'pb' vocabulary
  54. VOCAB = b"\x87"
  55. HIGH_BIT_SET = b"\x80"
  56. def setPrefixLimit(limit):
  57. """
  58. Set the limit on the prefix length for all Banana connections
  59. established after this call.
  60. The prefix length limit determines how many bytes of prefix a banana
  61. decoder will allow before rejecting a potential object as too large.
  62. @type limit: L{int}
  63. @param limit: The number of bytes of prefix for banana to allow when
  64. decoding.
  65. """
  66. global _PREFIX_LIMIT
  67. _PREFIX_LIMIT = limit
  68. _PREFIX_LIMIT = None
  69. setPrefixLimit(64)
  70. SIZE_LIMIT = 640 * 1024 # 640k is all you'll ever need :-)
  71. class Banana(protocol.Protocol, styles.Ephemeral):
  72. """
  73. L{Banana} implements the I{Banana} s-expression protocol, client and
  74. server.
  75. @ivar knownDialects: These are the profiles supported by this Banana
  76. implementation.
  77. @type knownDialects: L{list} of L{bytes}
  78. """
  79. # The specification calls these profiles but this implementation calls them
  80. # dialects instead.
  81. knownDialects = [b"pb", b"none"]
  82. prefixLimit = None
  83. sizeLimit = SIZE_LIMIT
  84. def setPrefixLimit(self, limit):
  85. """
  86. Set the prefix limit for decoding done by this protocol instance.
  87. @see: L{setPrefixLimit}
  88. """
  89. self.prefixLimit = limit
  90. self._smallestLongInt = -(2 ** (limit * 7)) + 1
  91. self._smallestInt = -(2 ** 31)
  92. self._largestInt = 2 ** 31 - 1
  93. self._largestLongInt = 2 ** (limit * 7) - 1
  94. def connectionReady(self):
  95. """Surrogate for connectionMade
  96. Called after protocol negotiation.
  97. """
  98. def _selectDialect(self, dialect):
  99. self.currentDialect = dialect
  100. self.connectionReady()
  101. def callExpressionReceived(self, obj):
  102. if self.currentDialect:
  103. self.expressionReceived(obj)
  104. else:
  105. # this is the first message we've received
  106. if self.isClient:
  107. # if I'm a client I have to respond
  108. for serverVer in obj:
  109. if serverVer in self.knownDialects:
  110. self.sendEncoded(serverVer)
  111. self._selectDialect(serverVer)
  112. break
  113. else:
  114. # I can't speak any of those dialects.
  115. log.msg(
  116. "The client doesn't speak any of the protocols "
  117. "offered by the server: disconnecting."
  118. )
  119. self.transport.loseConnection()
  120. else:
  121. if obj in self.knownDialects:
  122. self._selectDialect(obj)
  123. else:
  124. # the client just selected a protocol that I did not suggest.
  125. log.msg(
  126. "The client selected a protocol the server didn't "
  127. "suggest and doesn't know: disconnecting."
  128. )
  129. self.transport.loseConnection()
  130. def connectionMade(self):
  131. self.setPrefixLimit(_PREFIX_LIMIT)
  132. self.currentDialect = None
  133. if not self.isClient:
  134. self.sendEncoded(self.knownDialects)
  135. def gotItem(self, item):
  136. l = self.listStack
  137. if l:
  138. l[-1][1].append(item)
  139. else:
  140. self.callExpressionReceived(item)
  141. buffer = b""
  142. def dataReceived(self, chunk):
  143. buffer = self.buffer + chunk
  144. listStack = self.listStack
  145. gotItem = self.gotItem
  146. while buffer:
  147. assert self.buffer != buffer, "This ain't right: {} {}".format(
  148. repr(self.buffer),
  149. repr(buffer),
  150. )
  151. self.buffer = buffer
  152. pos = 0
  153. for ch in iterbytes(buffer):
  154. if ch >= HIGH_BIT_SET:
  155. break
  156. pos = pos + 1
  157. else:
  158. if pos > self.prefixLimit:
  159. raise BananaError(
  160. "Security precaution: more than %d bytes of prefix"
  161. % (self.prefixLimit,)
  162. )
  163. return
  164. num = buffer[:pos]
  165. typebyte = buffer[pos : pos + 1]
  166. rest = buffer[pos + 1 :]
  167. if len(num) > self.prefixLimit:
  168. raise BananaError(
  169. "Security precaution: longer than %d bytes worth of prefix"
  170. % (self.prefixLimit,)
  171. )
  172. if typebyte == LIST:
  173. num = b1282int(num)
  174. if num > SIZE_LIMIT:
  175. raise BananaError("Security precaution: List too long.")
  176. listStack.append((num, []))
  177. buffer = rest
  178. elif typebyte == STRING:
  179. num = b1282int(num)
  180. if num > SIZE_LIMIT:
  181. raise BananaError("Security precaution: String too long.")
  182. if len(rest) >= num:
  183. buffer = rest[num:]
  184. gotItem(rest[:num])
  185. else:
  186. return
  187. elif typebyte == INT:
  188. buffer = rest
  189. num = b1282int(num)
  190. gotItem(num)
  191. elif typebyte == LONGINT:
  192. buffer = rest
  193. num = b1282int(num)
  194. gotItem(num)
  195. elif typebyte == LONGNEG:
  196. buffer = rest
  197. num = b1282int(num)
  198. gotItem(-num)
  199. elif typebyte == NEG:
  200. buffer = rest
  201. num = -b1282int(num)
  202. gotItem(num)
  203. elif typebyte == VOCAB:
  204. buffer = rest
  205. num = b1282int(num)
  206. item = self.incomingVocabulary[num]
  207. if self.currentDialect == b"pb":
  208. # the sender issues VOCAB only for dialect pb
  209. gotItem(item)
  210. else:
  211. raise NotImplementedError(f"Invalid item for pb protocol {item!r}")
  212. elif typebyte == FLOAT:
  213. if len(rest) >= 8:
  214. buffer = rest[8:]
  215. gotItem(struct.unpack("!d", rest[:8])[0])
  216. else:
  217. return
  218. else:
  219. raise NotImplementedError(f"Invalid Type Byte {typebyte!r}")
  220. while listStack and (len(listStack[-1][1]) == listStack[-1][0]):
  221. item = listStack.pop()[1]
  222. gotItem(item)
  223. self.buffer = b""
  224. def expressionReceived(self, lst):
  225. """Called when an expression (list, string, or int) is received."""
  226. raise NotImplementedError()
  227. outgoingVocabulary = {
  228. # Jelly Data Types
  229. b"None": 1,
  230. b"class": 2,
  231. b"dereference": 3,
  232. b"reference": 4,
  233. b"dictionary": 5,
  234. b"function": 6,
  235. b"instance": 7,
  236. b"list": 8,
  237. b"module": 9,
  238. b"persistent": 10,
  239. b"tuple": 11,
  240. b"unpersistable": 12,
  241. # PB Data Types
  242. b"copy": 13,
  243. b"cache": 14,
  244. b"cached": 15,
  245. b"remote": 16,
  246. b"local": 17,
  247. b"lcache": 18,
  248. # PB Protocol Messages
  249. b"version": 19,
  250. b"login": 20,
  251. b"password": 21,
  252. b"challenge": 22,
  253. b"logged_in": 23,
  254. b"not_logged_in": 24,
  255. b"cachemessage": 25,
  256. b"message": 26,
  257. b"answer": 27,
  258. b"error": 28,
  259. b"decref": 29,
  260. b"decache": 30,
  261. b"uncache": 31,
  262. }
  263. incomingVocabulary = {}
  264. for k, v in outgoingVocabulary.items():
  265. incomingVocabulary[v] = k
  266. def __init__(self, isClient=1):
  267. self.listStack = []
  268. self.outgoingSymbols = copy.copy(self.outgoingVocabulary)
  269. self.outgoingSymbolCount = 0
  270. self.isClient = isClient
  271. def sendEncoded(self, obj):
  272. """
  273. Send the encoded representation of the given object:
  274. @param obj: An object to encode and send.
  275. @raise BananaError: If the given object is not an instance of one of
  276. the types supported by Banana.
  277. @return: L{None}
  278. """
  279. encodeStream = BytesIO()
  280. self._encode(obj, encodeStream.write)
  281. value = encodeStream.getvalue()
  282. self.transport.write(value)
  283. def _encode(self, obj, write):
  284. if isinstance(obj, (list, tuple)):
  285. if len(obj) > SIZE_LIMIT:
  286. raise BananaError("list/tuple is too long to send (%d)" % (len(obj),))
  287. int2b128(len(obj), write)
  288. write(LIST)
  289. for elem in obj:
  290. self._encode(elem, write)
  291. elif isinstance(obj, int):
  292. if obj < self._smallestLongInt or obj > self._largestLongInt:
  293. raise BananaError("int is too large to send (%d)" % (obj,))
  294. if obj < self._smallestInt:
  295. int2b128(-obj, write)
  296. write(LONGNEG)
  297. elif obj < 0:
  298. int2b128(-obj, write)
  299. write(NEG)
  300. elif obj <= self._largestInt:
  301. int2b128(obj, write)
  302. write(INT)
  303. else:
  304. int2b128(obj, write)
  305. write(LONGINT)
  306. elif isinstance(obj, float):
  307. write(FLOAT)
  308. write(struct.pack("!d", obj))
  309. elif isinstance(obj, bytes):
  310. # TODO: an API for extending banana...
  311. if self.currentDialect == b"pb" and obj in self.outgoingSymbols:
  312. symbolID = self.outgoingSymbols[obj]
  313. int2b128(symbolID, write)
  314. write(VOCAB)
  315. else:
  316. if len(obj) > SIZE_LIMIT:
  317. raise BananaError(
  318. "byte string is too long to send (%d)" % (len(obj),)
  319. )
  320. int2b128(len(obj), write)
  321. write(STRING)
  322. write(obj)
  323. else:
  324. raise BananaError(
  325. "Banana cannot send {} objects: {!r}".format(
  326. fullyQualifiedName(type(obj)), obj
  327. )
  328. )
  329. # For use from the interactive interpreter
  330. _i = Banana()
  331. _i.connectionMade()
  332. _i._selectDialect(b"none")
  333. def encode(lst):
  334. """Encode a list s-expression."""
  335. encodeStream = BytesIO()
  336. _i.transport = encodeStream
  337. _i.sendEncoded(lst)
  338. return encodeStream.getvalue()
  339. def decode(st):
  340. """
  341. Decode a banana-encoded string.
  342. """
  343. l = []
  344. _i.expressionReceived = l.append
  345. try:
  346. _i.dataReceived(st)
  347. finally:
  348. _i.buffer = b""
  349. del _i.expressionReceived
  350. return l[0]