Commits

Anonymous committed 09b75a7

Documented serializers

Comments (0)

Files changed (1)

docs/serializers.rst

+Serialization
+=============
+
+Serialization is the operation that converts objects in the memory into a
+bytestream that can be written to a file or sent over the network.
+Deserialization is the opposite of that, where objects are reconstructed from
+the bytestream. In PyHttpRPC, serialization is used to encapsulate the RPC
+request in a HTTP request.
+
+PyHttpRPC provides two alternative mechanisms for serialization: **Pickle**
+(the Python standard serialization mechanism) and **PyAMF** (AMF3 encoding
+using the third-part `PyAMF` library). Both mechanisms are capable of passing
+instances of classes to the a remote host by value without losing type
+information.
+
+
+Serialization security
+----------------------
+
+When instances of user defined classes are deserialized in the receiving end,
+the deserializer needs to have access to their class definitions. If the
+deserializer is allowed to freely import any class from anywhere, it would
+allow a malicious peer to execute arbitrary code. To prevent this, PyHttpRPC
+only allows automatic import of modules explicitly allowed by the developer.
+The :meth:`~pyhttprpc.serializer.base.BaseSerializer.add_allowed_import` method
+is used to permit the serializer to automatically import modules and classes.
+The argument given to this method is a regular expression, in either string
+or compiled form. If the expression matches an incoming class definition
+(in the form ``module.classname``), it is allowed to be autoimported. Otherwise
+a :class:`~pyhttprpc.DeserializationError` is raised.
+
+
+Pickle notes
+------------
+
+When using PyHttpRPC with Python 3.x exclusively, you probably want to use
+pickle protocol 3. The protocol level is set to 2 by default for compatibility
+with Python 2.x.
+
+
+PyAMF notes
+-----------
+
+When using PyAMF version 0.5.1 or earlier, classes whose instances are to be
+serialized must have constructors that can be called with no arguments. PyAMF
+version 0.6 lifts this restriction.
+
+PyHttpRPC overrides :func:`pyamf.get_class_alias` function to implement the
+import permissions check. To prevent this "Monkey patching", just pass
+``monkey_patch=False`` to the constructor of
+:class:`~pyhttprpc.serializer.pyamf.PyAMFSerializer`. You can then use
+:func:`pyamf.register_package` and similar functions to define the allowed
+imports, since PyAMF does not import anything by default.