Package: twnet-parser
A teeworlds network protocol library, designed according to sans I/O (http://sans-io.readthedocs.io/) principlesTHIS LIBRARY IS IN EARLY DEVELOPMENTDo not get bamboozled by the mature looking readme!This project is not in a very usable state yet. It is in very early development!APIs might change and many essential features are missing!installpipinstalltwnet_parsersample usageimporttwnet_parser.packetpacket=twnet_parser.packet.parse7(b'\x04\x0a\x00\xcf\x2e\xde\x1d\04')# 0.7 closeprint(packet)# => <class: 'TwPacket'>: {'version': '0.7', 'header': <class: 'Header'>, 'messages': [<class: 'CtrlMessage'>]}print(packet.header)# => <class: 'Header'>: {'flags': <class: 'PacketFlags7, 'size': 0, 'ack': 10, 'token': b'\xcf.\xde\x1d', 'num_chunks': 0}print(packet.header.flags)# => <class: 'PacketFlags7'>: {'control': True, 'resend': False, 'compression': False, 'connless': False}formsginpacket.messages:print(msg.message_name)# => closeMore examples can be found in theexamples/folder:map downloader clientflood client (connect multiple tees to a server)pcap printer (capture with tcpdump and print teeworlds traffic details)FeaturesFeature0.70.6Deserialize packet headers:heavy_check_mark::heavy_check_mark:Deserialize chunk headers:heavy_check_mark::heavy_check_mark:Deserialize messages90%90%Deserialize snapshotsDeserialize connless packets:heavy_check_mark::heavy_check_mark:Serialize packet headers:heavy_check_mark::heavy_check_mark:Serialize chunk headers:heavy_check_mark::heavy_check_mark:Serialize messages90%90%Serialize snapshotsSerialize connless packets:heavy_check_mark::heavy_check_mark:Non-Features (also not planned for this library)FeatureStatusWhere to find itNetworking:x:TODO: link if someone implemented it on topProtocol version detection:x:TODO: link if someone implemented it on topTrack sequence number state:x:TODO: link if someone implemented it on topTrack connection state:x:TODO: link if someone implemented it on topLook elsewhere for these features. Or use this library to implement them on top.This project is intentionally only covering parsing the protocol.
Not fully implemeting a state machine of the protocol.
Or a fully working client / server software.If you want to build something with this library
you do have to understand how the protocol works
and when the client and server have to send what.Thisprotocol documentationshould get you started to understand the basics.Convenient defaults and fully customizablefromtwnet_parser.packetimportTwPacketfromtwnet_parser.messages7.game.cl_call_voteimportMsgClCallVote"""The call to packet.pack() generatesa valid byte array that can be sent as an udp payloadIt uses default values for things like:security token, acknowledge number, packet flags,chunk header (flags, size, seq),vote type, vote value, vote reason, vote forceIt computes a valid chunk header size field basedon the payload length.It sets the correct num chunks field in the packet headerbased on the amount of messages you added (1 in this case)While this has all fields set that packet would be dropped by a vanillaimplementation because the security token and sequence number is wrong.So you have to take care of those your self."""packet=TwPacket()msg=MsgClCallVote()packet.messages.append(msg)packet.pack()# => b'\x00\x00\x01\xff\xff\xff\xff\x00\x00\x80\x01default\x00default\x00default\x00\x00'"""Here we also send a Call vote message.But this time we set a security token and a few other fields.Note that we set num_chunks to 6 which is wrong becausewe only send one message (MsgClCallVote).But this library allows you to do so.And it will not compute the correct amount.But use your explicitly set wrong one instead.This allows you to have full control and craft any kind of packet.May it be correct or not."""packet=TwPacket()packet.header.token=b'\x48\x1f\x93\xd7'packet.header.num_chunks=6packet.header.ack=638packet.header.flags.control=Falsepacket.header.flags.compression=Falsemsg=MsgClCallVote()msg.header.seq=10msg.type='option'msg.value='test'msg.reason=''msg.force=Falsepacket.messages.append(msg)packet.pack()# => b'\x02~\x06H\x1f\x93\xd7\x00\x00\x80\x01option\x00test\x00\x00\x00'Zero dependencies by defaultRunningpip install twnet_parserwill not install any additional packages.But there is an optional dependency for huffman compression.
By default twnet_parser is using the huffman compression code from theTeeAIproject which is written in pure python.
If you havelibtw2-huffmaninstalled it will use that one instead.
Because it is faster since it is written in rust and has better error handling.
But since it is so much overhead it is not installed by default to keep twnet_parser light weight.You can install it by runningpip install libtw2-huffmanor by runningpip install -r requirements/optional.txtYou can also check which huffman backend is currently active with these lines of codeimporttwnet_parser.huffmanprint(twnet_parser.huffman.backend_name())# => rust-libtw2 or python-TeeAIdevelopment setupgitclonehttps://gitlab.com/teeworlds-network/twnet_parsercdtwnet_parser
python-mvenvvenvsourcevenv/bin/activate
pipinstall-rrequirements/dev.txt
pre-commitinstall--hook-typecommit-msgtests and linting# dev dependenciespipinstall-rrequirements/dev.txt# run unit testspytest.# run style linterpylintsrc/# run type checkermypysrc/# or use the bundle script that runs all tests./scripts/run_tests.shpackage and release# manualpipinstall-rrequirements/dev.txtversion=0.0.2
sed-i"s/^version =.*/version =$version/"setup.cfg
python-mbuild
gittag-a"v$version"-m"# version$version"python-mtwineuploaddist/*# or use the interactive convience script./scripts/release.sh