In more complicated cases, for example an Avatar that
represents a player object which is persistent in the game universe,
-we will want connections from the same player to use the same
-Avatar.
Another thing which is necessary in more complicated scenarios
-is notifying a player asynchronously. While it is possible, of
-course, to allow a player to call
-perspective_remoteListener(referencable) that would
-mean both duplication of code and a higher latency in logging in,
-both bad.
Avatar.
+
+Another thing which is necessary in more complicated scenarios is
+notifying a player asynchronously. While it is possible, of course, to
+allow a player to
+call perspective_remoteListener(referencable) that would
+mean both duplication of code and a higher latency in logging in, both
+bad.
In previous sections all realms looked to be identical. In this one we will show the usefulness of realms in accomplishing diff --git a/doc/core/howto/pb-copyable.xhtml b/doc/core/howto/pb-copyable.xhtml index 42d1bf3..f4acffb 100644 --- a/doc/core/howto/pb-copyable.xhtml +++ b/doc/core/howto/pb-copyable.xhtml @@ -69,25 +69,25 @@ dictionaries because they also contain (or reference) code, which can modify other data structures when executed. Once previously-trusted data is subverted, the rest of the program is compromised.
-The built-in Python batteries included
classes are relatively
-tame, but you still wouldn't want to let a foreign program use them to
-create arbitrary objects in your namespace or on your computer. Imagine a
-protocol that involved sending a file-like object with a read()
-method that was supposed to used later to retrieve a document. Then imagine
-what if that object were created with
-os.fdopen("~/.gnupg/secring.gpg"). Or an instance of
-telnetlib.Telnet("localhost", "chargen").
Classes you've written for your own program are likely to have far more
-power. They may run code during __init__, or even have special
-meaning simply because of their existence. A program might have
-User objects to represent user accounts, and have a rule that
-says all User objects in the system are referenced when
-authorizing a login session. (In this system, User.__init__
-would probably add the object to a global list of known users). The simple
-act of creating an object would give access to somebody. If you could be
-tricked into creating a bad object, an unauthorized user would get
-access.
The built-in Python batteries included
classes are
+relatively tame, but you still wouldn't want to let a foreign program
+use them to create arbitrary objects in your namespace or on your
+computer. Imagine a protocol that involved sending a file-like object
+with a read() method that was supposed to used later to
+retrieve a document. Then imagine what if that object were created
+with os.fdopen("~/.gnupg/secring.gpg"). Or an instance
+of telnetlib.Telnet("localhost", "chargen").
Classes you've written for your own program are likely to have far
+more power. They may run code during __init__, or even
+have special meaning simply because of their existence. A program
+might have User objects to represent user accounts, and
+have a rule that says all User objects in the system are
+referenced when authorizing a login session. (In this
+system, User.__init__ would probably add the object to a
+global list of known users). The simple act of creating an object
+would give access to somebody. If you could be tricked into creating a
+bad object, an unauthorized user would get access.
So object creation needs to be part of a system's security design. The
dotted line between trusted inside
and untrusted outside
needs
@@ -117,18 +117,19 @@ contents of the object.
setUnjellyableForClass function Note that, in this context, Note that, in this
+context, unjelly
is
-a verb with the opposite meaning of jelly
. The verb to jelly
-means to serialize an object or data structure into a sequence of bytes (or
-other primitive transmittable/storable representation), while to
-unjelly
means to unserialize the bytestream into a live object in the
-receiver's memory space. Unjellyable
is a noun, (not an
+--> unjelly
is a verb with the opposite meaning
+of jelly
. The verb to jelly
means to serialize an object
+or data structure into a sequence of bytes (or other primitive
+transmittable/storable representation), while to unjelly
means
+to unserialize the bytestream into a live object in the receiver's
+memory space. Unjellyable
is a noun, (not an
adjective), referring to the the class that serves as a destination or
-recipient of the unjellying process. A is unjellyable into B
means
-that a serialized representation A (of some remote object) can be
-unserialized into a local object of type B. It is these objects B
-that are the Unjellyable
second argument of the
-setUnjellyableForClass function.A is unjellyable into B
+means that a serialized representation A (of some remote object) can
+be unserialized into a local object of type B. It is these
+objects B
that are the Unjellyable
second argument of
+the setUnjellyableForClass function.
In particular, unjellyable
does not mean cannot be
jellied
. jellying, serializing
, and
This function takes a remote/sender class reference (either the
-fully-qualified name as used by the sending end, or a class object from
-which the name can be extracted), and a local/recipient class (used to
-create the local representation for incoming serialized objects). Whenever
-the remote end sends an object, the class name that they transmit is looked
-up in the table controlled by this function. If a matching class is found,
-it is used to create the local object. If not, you get the
-InsecureJelly exception.
In general you expect both ends to share the same codebase: either you
-control the program that is running on both ends of the wire, or both
-programs share some kind of common language that is implemented in code
-which exists on both ends. You wouldn't expect them to send you an object of
-the MyFooziWhatZit class unless you also had a definition for that class. So
-it is reasonable for the Jelly layer to reject all incoming classes except
-the ones that you have explicitly marked with
-setUnjellyableForClass. But keep in mind that the sender's idea
-of a User object might differ from the recipient's, either
-through namespace collisions between unrelated packages, version skew
-between nodes that haven't been updated at the same rate, or a malicious
-intruder trying to cause your code to fail in some interesting or
-potentially vulnerable way.
InsecureJelly exception.
+
+In general you expect both ends to share the same codebase: either
+you control the program that is running on both ends of the wire, or
+both programs share some kind of common language that is implemented
+in code which exists on both ends. You wouldn't expect them to send
+you an object of the MyFooziWhatZit class unless you also had a
+definition for that class. So it is reasonable for the Jelly layer to
+reject all incoming classes except the ones that you have explicitly
+marked with setUnjellyableForClass. But keep in mind that
+the sender's idea of a User object might differ from the
+recipient's, either through namespace collisions between unrelated
+packages, version skew between nodes that haven't been updated at the
+same rate, or a malicious intruder trying to cause your code to fail
+in some interesting or potentially vulnerable way.
The sending side has a class called LilyPond. To make this
-eligble for transport through callRemote (either as an
-argument, a return value, or something referenced by either of those [like a
-dictionary value]), it must inherit from one of the four Serializable classes. In this section,
-we focus on Copyable.
-The copyable subclass of LilyPond is called
-CopyPond. We create an instance of it and send it through
-callRemote as an argument to the receiver's
-remote_takePond method. The Jelly layer will serialize
-(jelly
) that object as an instance with a class name of
+
The sending side has a class called LilyPond. To make
+this eligble for transport through callRemote (either as
+an argument, a return value, or something referenced by either of
+those [like a dictionary value]), it must inherit from one of the
+four Serializable
+classes. In this section, we focus on Copyable. The copyable subclass
+of LilyPond is called CopyPond. We create an
+instance of it and send it through callRemote as an
+argument to the receiver's remote_takePond method. The
+Jelly layer will serialize (jelly
) that object as an instance
+with a class name of
copy_sender.CopyPond
and some chunk of data that represents the
-object's state. pond.__class__.__module__ and
-pond.__class__.__name__ are used to derive the class name
-string. The object's getStateToCopy method is
-used to get the state: this is provided by pb.Copyable, and the default just retrieves
-self.__dict__. This works just like the optional
-__getstate__ method used by pickle. The pair of
-name and state are sent over the wire to the receiver.
The receiving end defines a local class named ReceiverPond
-to represent incoming LilyPond instances. This class derives
-from the sender's LilyPond class (with a fully-qualified name
-of copy_sender.LilyPond), which specifies how we expect it to
-behave. We trust that this is the same LilyPond class as the
-sender used. (At the very least, we hope ours will be able to accept a state
-created by theirs). It also inherits from pb.RemoteCopy, which is a requirement for all
-classes that act in this local-representative role (those which are given to
-the second argument of setUnjellyableForClass).
-RemoteCopy provides the methods that tell the Jelly layer how
-to create the local object from the incoming serialized state.
pond.__class__.__module__
+and pond.__class__.__name__ are used to derive the class
+name string. The object's getStateToCopy method is used
+to get the state: this is provided by pb.Copyable, and the default just
+retrieves self.__dict__. This works just like the
+optional __getstate__ method used
+by pickle. The pair of name and state are sent over the
+wire to the receiver.
+
+The receiving end defines a local class
+named ReceiverPond to represent
+incoming LilyPond instances. This class derives from the
+sender's LilyPond class (with a fully-qualified name
+of copy_sender.LilyPond), which specifies how we expect
+it to behave. We trust that this is the same LilyPond
+class as the sender used. (At the very least, we hope ours will be
+able to accept a state created by theirs). It also inherits
+from pb.RemoteCopy,
+which is a requirement for all classes that act in this
+local-representative role (those which are given to the second
+argument
+of setUnjellyableForClass). RemoteCopy
+provides the methods that tell the Jelly layer how to create the local
+object from the incoming serialized state.
Then setUnjellyableForClass is used to register the two
classes. This has two effects: instances of the remote class (the first
@@ -211,17 +217,17 @@ argument) will be allowed in through the security layer, and instances of
the local class (the second argument) will be used to contain the state that
is transmitted when the sender serializes the remote object.
When the receiver unserializes (unjellies
) the object, it will
-create an instance of the local ReceiverPond class, and hand
-the transmitted state (usually in the form of a dictionary) to that object's
-When the receiver unserializes (unjellies
) the object, it
+will create an instance of the local ReceiverPond class,
+and hand the transmitted state (usually in the form of a dictionary)
+to that object's setCopyableState method.
-This acts just like the __setstate__ method that
-pickle uses when unserializing an object.
-getStateToCopy/setCopyableState are distinct from
-__getstate__/__setstate__ to allow objects to be
-persisted (across time) differently than they are transmitted (across
-[memory]space).
__setstate__ method
+that pickle uses when unserializing an
+object. getStateToCopy/setCopyableState are
+distinct from __getstate__/__setstate__ to
+allow objects to be persisted (across time) differently than they are
+transmitted (across [memory]space).
When this is run, it produces the following output:
@@ -247,24 +253,25 @@ Main loop terminated.By overriding getStateToCopy and
-setCopyableState, you can control how the object is transmitted
-over the wire. For example, you might want perform some data-reduction:
-pre-compute some results instead of sending all the raw data over the wire.
-Or you could replace references to a local object on the sender's side with
-markers before sending, then upon receipt replace those markers with
-references to a receiver-side proxy that could perform the same operations
-against a local cache of data.
By overriding getStateToCopy
+and setCopyableState, you can control how the object is
+transmitted over the wire. For example, you might want perform some
+data-reduction: pre-compute some results instead of sending all the
+raw data over the wire. Or you could replace references to a local
+object on the sender's side with markers before sending, then upon
+receipt replace those markers with references to a receiver-side proxy
+that could perform the same operations against a local cache of
+data.
Another good use for getStateToCopy is to implement
-local-only
attributes: data that is only accessible by the local
-process, not to any remote users. For example, a .password
-attribute could be removed from the object state before sending to a remote
-system. Combined with the fact that Copyable objects return
-unchanged from a round trip, this could be used to build a
-challenge-response system (in fact PB does this with
-pb.Referenceable objects to implement authorization as
-described here).
local-onlyattributes: data that is only accessible by the +local process, not to any remote users. For example, +a
.password attribute could be removed from the object
+state before sending to a remote system. Combined with the fact
+that Copyable objects return unchanged from a round trip,
+this could be used to build a challenge-response system (in fact PB
+does this with pb.Referenceable objects to implement
+authorization as described here).
Whatever getStateToCopy returns from the sending object will
be serialized and sent over the wire; setCopyableState gets
@@ -276,11 +283,12 @@ the object it lives in.
In this example, the classes are defined in a separate source file, which
-also sets up the binding between them. The SenderPond and
-ReceiverPond are unrelated save for this binding: they happen
-to implement the same methods, but use different internal instance variables
-to accomplish them.
In this example, the classes are defined in a separate source file,
+which also sets up the binding between
+them. The SenderPond and ReceiverPond are
+unrelated save for this binding: they happen to implement the same
+methods, but use different internal instance variables to accomplish
+them.
The recipient of the object doesn't even have to import the class
definition into their namespace. It is sufficient that they import the class
@@ -426,26 +434,27 @@ object called the observer
this is actually a RemoteCacheObserver, but it isn't very
-useful to subclass or modify, so simply treat it as a little demon that sits
-in your pb.Cacheable class and helps you distribute change
-notifications. The only useful thing to do with it is to run its
-callRemote method, which acts just like a normal
-pb.Referenceable's method of the same name.
+useful to subclass or modify, so simply treat it as a little demon
+that sits in your pb.Cacheable class and helps you
+distribute change notifications. The only useful thing to do with it
+is to run its callRemote method, which acts just like a
+normal pb.Referenceable's method of the same name.
stoppedObserving, is called when the
remote cache goes away, so that you can stop sending updates.
-On the receiver end, you make your cache class inherit from pb.RemoteCache, and implement the
-setCopyableState as you would for a pb.RemoteCopy
-object. In addition, you must implement methods to receive the updates sent
-to the observer by the pb.Cacheable: these methods should have
-names that start with observe_, and match the
-callRemote invocations from the sender side just as the usual
-remote_* and perspective_* methods match normal
-callRemote calls.
On the receiver end, you make your cache class inherit
+from pb.RemoteCache,
+and implement the setCopyableState as you would for
+a pb.RemoteCopy object. In addition, you must implement
+methods to receive the updates sent to the observer by
+the pb.Cacheable: these methods should have names that
+start with observe_, and match
+the callRemote invocations from the sender side just as
+the usual remote_* and perspective_* methods
+match normal callRemote calls.
The first time a reference to the pb.Cacheable object is
sent to any particular recipient, a sender-side Observer will be created for
@@ -455,10 +464,10 @@ returns is sent to the remote end and turned into a local representation
using setCopyableState just like pb.RemoteCopy,
described above (in fact it inherits from that class).
After that, your setter
functions on the sender side should call
-callRemote on the Observer, which causes observe_*
-methods to run on the receiver, which are then supposed to update the
-receiver-local (cached) state.
After that, your setter
functions on the sender side should
+call callRemote on the Observer, which
+causes observe_* methods to run on the receiver, which
+are then supposed to update the receiver-local (cached) state.
When the receiver stops following the cached object and the last
reference goes away, the pb.RemoteCache object can be freed.
@@ -471,12 +480,13 @@ used to tell the pb.Cacheable that the Observer has gone
away.
With the pb.Cacheable and pb.RemoteCache
-classes in place, bound together by a call to
-pb.setUnjellyableForClass, all that remains is to pass a
-reference to your pb.Cacheable over the wire to the remote end.
-The corresponding pb.RemoteCache object will automatically be
-created, and the matching methods will be used to keep the receiver-side
-slave object in sync with the sender-side master object.
pb.setUnjellyableForClass, all that remains is to pass
+a reference to your pb.Cacheable over the wire to the
+remote end. The corresponding pb.RemoteCache object will
+automatically be created, and the matching methods will be used to
+keep the receiver-side slave object in sync with the sender-side
+master object.
twisted.spread.flavors,
where pb.Cacheable is implemented.
- twisted.manhole.explorer uses
- Cacheable, and does some fairly interesting things with it.twisted.manhole.explorer
+ uses Cacheable, and does some fairly interesting things
+ with it.Imagine how you would write a chat server using PB. The first step might
-be a ChatServer object which had a bunch of
-pb.RemoteReferences that point at user clients. Pretend that
-those clients offered a remote_print method which lets the
-server print a message on the user's console. In that case, the server might
-look something like this:
Imagine how you would write a chat server using PB. The first step
+might be a ChatServer object which had a bunch
+of pb.RemoteReferences that point at user
+clients. Pretend that those clients offered
+a remote_print method which lets the server print a
+message on the user's console. In that case, the server might look
+something like this:
class ChatServer(pb.Referenceable):
@@ -59,12 +60,13 @@ class ChatServer(pb.Referenceable):
message))
-For now, assume that all clients have somehow acquired a
-pb.RemoteReference to this ChatServer object,
-perhaps using pb.Root and getRootObject as
-described in the previous chapter. In this
-scheme, when a user sends a message to the group, their client runs
-something like the following:
For now, assume that all clients have somehow acquired
+a pb.RemoteReference to this ChatServer
+object, perhaps using pb.Root
+and getRootObject as described in
+the previous chapter. In this scheme,
+when a user sends a message to the group, their client runs something
+like the following:
remotegroup.callRemote("sendMessage", "alice", "Hi, my name is alice.")
@@ -94,15 +96,15 @@ cryptographic literature.
(In general, learn to get suspicious if you see any argument of a
remotely-invokable method described as must be X
)
-The best way to fix this is to keep track of the user's name locally,
-rather than asking them to send it to the server with each message. The best
-place to keep state is in an object, so this suggests we need a per-user
-object. Rather than choosing an obvious namethe
-obvious name is clearly
-ServerSidePerUserObjectWhichNobodyElseHasAccessTo, but because
-python makes everything else so easy to read, it only seems fair to make
-your audience work for something, let's call this the
-User class.
+
The best way to fix this is to keep track of the user's name
+locally, rather than asking them to send it to the server with each
+message. The best place to keep state is in an object, so this
+suggests we need a per-user object. Rather than choosing an obvious
+namethe obvious name is
+clearly ServerSidePerUserObjectWhichNobodyElseHasAccessTo,
+but because python makes everything else so easy to read, it only
+seems fair to make your audience work for something,
+let's call this the User class.
@@ -133,27 +135,30 @@ class ChatServer:
user.send("<%s> says: %s" % (from_username, message))
-Again, assume that each remote client gets access to a single
-User object, which is created with the proper username.
+Again, assume that each remote client gets access to a
+single User object, which is created with the proper
+username.
Note how the ChatServer object has no remote access: it
isn't even pb.Referenceable anymore. This means that all access
to it must be mediated through other objects, with code that is under your
control.
-As long as Alice only has access to her own User object, she
-can no longer spoof Bob. The only way for her to invoke
-ChatServer.sendMessage is to call her User
-object's remote_sendMessage method, and that method uses its
-own state to provide the from_username argument. It doesn't
-give her any way to change that state.
-
-This restriction is important. The User object is able to
-maintain its own integrity because there is a wall between the object and
-the client: the client cannot inspect or modify internal state, like the
-.name attribute. The only way through this wall is via remote
-method invocations, and the only control Alice has over those invocations is
-when they get invoked and what arguments they are given.
+As long as Alice only has access to her own User
+object, she can no longer spoof Bob. The only way for her to
+invoke ChatServer.sendMessage is to call
+her User object's remote_sendMessage method,
+and that method uses its own state to provide
+the from_username argument. It doesn't give her any way
+to change that state.
+
+This restriction is important. The User object is able
+to maintain its own integrity because there is a wall between the
+object and the client: the client cannot inspect or modify internal
+state, like the .name attribute. The only way through
+this wall is via remote method invocations, and the only control Alice
+has over those invocations is when they get invoked and what arguments
+they are given.
No object can maintain its integrity against local threats: by design,
@@ -165,12 +170,12 @@ everything the original object was able to do.
Unforgeable References
-Now suppose you wanted to implement group parameters, for example a mode
-in which nobody was allowed to talk about mattresses because some users were
-sensitive and calming them down after someone said mattress
is a
-hassle that were best avoided altogether. Again, per-group state implies a
-per-group object. We'll go out on a limb and call this the
-Group object:
+Now suppose you wanted to implement group parameters, for example a
+mode in which nobody was allowed to talk about mattresses because some
+users were sensitive and calming them down after someone
+said mattress
is a hassle that were best avoided
+altogether. Again, per-group state implies a per-group object. We'll
+go out on a limb and call this the Group object:
class User(pb.Referenceable):
@@ -207,14 +212,14 @@ class ChatServer:
-This example takes advantage of the fact that
-pb.Referenceable objects sent over a wire can be returned to
-you, and they will be turned into references to the same object that you
-originally sent. The client cannot modify the object in any way: all they
-can do is point at it and invoke its remote_* methods. Thus,
-you can be sure that the .name attribute remains the same as
-you left it. In this case, the client code would look something like
-this:
+This example takes advantage of the fact
+that pb.Referenceable objects sent over a wire can be
+returned to you, and they will be turned into references to the same
+object that you originally sent. The client cannot modify the object
+in any way: all they can do is point at it and invoke
+its remote_* methods. Thus, you can be sure that
+the .name attribute remains the same as you left it. In
+this case, the client code would look something like this:
class ClientThing(pb.Referenceable):
@@ -228,22 +233,25 @@ class ClientThing(pb.Referenceable):
group.callRemote("send", self.remoteUser, "hi everybody")
-The User object is sent from the server side, and is turned
-into a pb.RemoteReference when it arrives at the client. The
-client sends it back to Group.remote_send, and PB turns it back
-into a reference to the original User when it gets there.
-Group.remote_send can then use its .name attribute
-as the sender of the message.
+The User object is sent from the server side, and is
+turned into a pb.RemoteReference when it arrives at the
+client. The client sends it back to Group.remote_send,
+and PB turns it back into a reference to the
+original User when it gets
+there. Group.remote_send can then use
+its .name attribute as the sender of the message.
Third party references (there aren't any)
-This technique also relies upon the fact that the
-pb.Referenceable reference can only come from someone
-who holds a corresponding pb.RemoteReference. The design of the
-serialization mechanism (implemented in twisted.spread.jelly: pb, jelly, spread.. get it? Look for
+
This technique also relies upon the fact that
+the pb.Referenceable reference can only come
+from someone who holds a
+corresponding pb.RemoteReference. The design of the
+serialization mechanism (implemented
+in twisted.spread.jelly: pb, jelly,
+spread.. get it? Look for
banana
, too. What other networking framework
can claim API names based on sandwich ingredients?) makes it impossible for
a client to obtain a reference that they weren't explicitly given.
@@ -253,13 +261,15 @@ number won't be in the dict, and no amount of guessing by a malicious client
will give them anything else. The dict goes away when the connection is
dropped, further limiting the scope of those references.
-Futhermore, it is not possible for Bob to send his
-User reference to Alice (perhaps over some other PB channel
-just between the two of them). Outside the context of Bob's connection to
-the server, that reference is just a meaningless number. To prevent
-confusion, PB will tell you if you try to give it away: when you try to hand
-a pb.RemoteReference to a third party, you'll get an exception
-(implemented with an assert in pb.py:364 RemoteReference.jellyFor).
+Futhermore, it is not possible for Bob to
+send his User reference to Alice (perhaps over
+some other PB channel just between the two of them). Outside the
+context of Bob's connection to the server, that reference is just a
+meaningless number. To prevent confusion, PB will tell you if you try
+to give it away: when you try to hand
+a pb.RemoteReference to a third party, you'll get an
+exception (implemented with an assert in pb.py:364
+RemoteReference.jellyFor).
This helps the security model somewhat: only the client you gave the
reference to can cause any damage with it. Of course, the client might be a
@@ -286,9 +296,10 @@ reference to the wrong object.
-But again, note the vulnerability. If Alice holds a
-RemoteReference to any object on the server side that
-has a .name attribute, she can use that name as a spoofed
+
But again, note the vulnerability. If Alice holds
+a RemoteReference to any object on the server
+side that has a .name attribute, she can use that name as
+a spoofed
from
parameter. As a simple example, what if her client code looked
like:
@@ -312,23 +323,25 @@ and she has accomplished her lifelong goal.
Argument Typechecking
-There are two techniques to close this hole. The first is to have your
-remotely-invokable methods do type-checking on their arguments: if
-Group.remote_send asserted isinstance(from_user,
-User) then Alice couldn't use non-User objects to do her spoofing,
-and hopefully the rest of the system is designed well enough to prevent her
-from obtaining access to somebody else's User object.
+There are two techniques to close this hole. The first is to have
+your remotely-invokable methods do type-checking on their arguments:
+if Group.remote_send asserted isinstance(from_user,
+User) then Alice couldn't use non-User objects to do her
+spoofing, and hopefully the rest of the system is designed well enough
+to prevent her from obtaining access to somebody else's User
+object.
Objects as Capabilities
-The second technique is to avoid having the client send you the objects
-altogether. If they don't send you anything, there is nothing to verify. In
-this case, you would have to have a per-user-per-group object, in which the
-remote_send method would only take a single
-message argument. The UserGroup object is created
-with references to the only User and Group objects
-that it will ever use, so no lookups are needed:
+The second technique is to avoid having the client send you the
+objects altogether. If they don't send you anything, there is nothing
+to verify. In this case, you would have to have a per-user-per-group
+object, in which the remote_send method would only take a
+single message argument. The UserGroup
+object is created with references to the only User
+and Group objects that it will ever use, so no lookups
+are needed:
class UserGroup(pb.Referenceable):
@@ -352,17 +365,17 @@ class Group:
self.users.append(user)
-The only message-sending method Alice has left is
-UserGroup.remote_send, and it only accepts a message: there are
-no remaining ways to influence the from
name.
+The only message-sending method Alice has left
+is UserGroup.remote_send, and it only accepts a message:
+there are no remaining ways to influence the from
name.
In this model, each remotely-accessible object represents a very small
set of capabilities. Security is achieved by only granting a minimal set of
abilities to each remote user.
-PB provides a shortcut which makes this technique easier to use. The
-Viewable class will be discussed below.
+PB provides a shortcut which makes this technique easier to
+use. The Viewable class will be
+discussed below.
Avatars and Perspectives
@@ -380,17 +393,18 @@ provide additional data, then call other methods which get things done.
what serves as the Avatar?
, and how does the user get access to
it?
.
-For PB, the first question is easy. The Avatar is a remotely-accessible
-object which can run code: this is a perfect description of
-pb.Referenceable and its subclasses. We shall defer the second
-question until the next section.
+For PB, the first question is easy. The Avatar is a
+remotely-accessible object which can run code: this is a perfect
+description of pb.Referenceable and its subclasses. We
+shall defer the second question until the next section.
-In the example above, you can think of the ChatServer and
-Group objects as a service. The User object is the
-user's server-side representative: everything the user is capable of doing
-is done by running one of its methods. Anything that the server wants to do
-to the user (change their group membership, change their name, delete their
-pet cat, whatever) is done by manipulating the User object.
+In the example above, you can think of the ChatServer
+and Group objects as a service. The User
+object is the user's server-side representative: everything the user
+is capable of doing is done by running one of its methods. Anything
+that the server wants to do to the user (change their group
+membership, change their name, delete their pet cat, whatever) is done
+by manipulating the User object.
There are multiple User objects living in peace and harmony around the
ChatServer. Each has a different point of view on the services provided by
@@ -400,10 +414,11 @@ These different points of view are called Perspectives
. This is the
origin of the term Perspective
in Perspective Broker
: PB
provides and controls (i.e. brokers
) access to Perspectives.
-Once upon a time, these local-representative objects were actually called
-pb.Perspective. But this has changed with the advent of the
-rewritten cred system, and now the more generic term for a local
-representative object is an Avatar. But you will still see reference to
+
Once upon a time, these local-representative objects were actually
+called pb.Perspective. But this has changed with the
+advent of the rewritten cred system, and now the more generic term for
+a local representative object is an Avatar. But you will still see
+reference to
Perspective
in the code, the docs, and the module namesWe could just go ahead and rename Perspective Broker to be
Avatar Broker, but 1) that would cause massive compatibility problems, and 2)
@@ -414,26 +429,29 @@ twisted.spread would then have to be renamed twisted.alphabetsoup, and then
the whole food-pun thing would start all over again.. Just remember
that perspectives and avatars are basically the same thing.
-Despite all we've been telling you about how
-Avatars are more of a concept than an actual class, the base class from
-which you can create your server-side avatar-ish objects is, in fact, named
-pb.AvatarThe avatar-ish class is named
-pb.Avatar because pb.Perspective was already
-taken, by the (now obsolete) oldcred perspective-ish class. It is a pity,
-but it simply wasn't possible both replace pb.Perspective
+Despite all we've been telling you about
+how Avatars are more of a concept than an actual class, the base class
+from which you can create your server-side avatar-ish objects is, in
+fact, named pb.AvatarThe
+avatar-ish class is named pb.Avatar
+because pb.Perspective was already taken, by the (now
+obsolete) oldcred perspective-ish class. It is a pity, but it simply
+wasn't possible both replace pb.Perspective
in-place and maintain a reasonable level of
-backwards-compatibility.. These objects behave very much like
-pb.Referenceable. The only difference is that instead of
-offering remote_FOO
methods, they offer perspective_FOO
-methods.
-
-The other way in which pb.Avatar differs from
-pb.Referenceable is that the avatar objects are designed to be
-the first thing retrieved by a cred-using remote client. Just as
-PBClientFactory.getRootObject gives the client access to a
-pb.Root object (which can then provide access to all kinds of
-other objects), PBClientFactory.login gives client access to a
-pb.Avatar object (which can return other references).
+backwards-compatibility.. These objects behave very much
+like pb.Referenceable. The only difference is that
+instead of offering remote_FOO
methods, they
+offer perspective_FOO
methods.
+
+The other way in which pb.Avatar differs
+from pb.Referenceable is that the avatar objects are
+designed to be the first thing retrieved by a cred-using remote
+client. Just as PBClientFactory.getRootObject gives the
+client access to a pb.Root object (which can then provide
+access to all kinds of other
+objects), PBClientFactory.login gives client access to
+a pb.Avatar object (which can return other
+references).
So, the first half of using cred in your PB application is to create an
Avatar object which implements perspective_ methods and is
@@ -488,10 +506,11 @@ again with two users this time.
When the client runs login to request the Perspective,
-they can provide it with an optional client argument (which
-must be a pb.Referenceable object). If they do, then a
-reference to that object will be handed to the realm's
-requestAvatar in the mind argument.
+they can provide it with an optional client argument
+(which must be a pb.Referenceable object). If they do,
+then a reference to that object will be handed to the
+realm's requestAvatar in the mind
+argument.
The server-side Perspective can use it to invoke remote methods on
something in the client, so that the client doesn't always have to drive the
@@ -522,30 +541,31 @@ Perspective.
our server-side Avatar. It implements a perspective_foo method
that is exposed to the remote client.
-Second, we created a realm (an object which implements
-IRealm, and therefore implements requestAvatar).
-This realm manufactures MyPerspective objects. It makes as many
-as we want, and names each one with the avatarID (a username) that comes out
-of the checkers. This MyRealm object returns two other objects as well,
-which we will describe later.
+Second, we created a realm (an object which
+implements IRealm, and therefore
+implements requestAvatar). This realm
+manufactures MyPerspective objects. It makes as many as
+we want, and names each one with the avatarID (a username) that comes
+out of the checkers. This MyRealm object returns two other objects as
+well, which we will describe later.
Third, we created a portal to hold this realm. The portal's job is to
dispatch incoming clients to the credential checkers, and then to request
Avatars for any which survive the authentication process.
-Fourth, we made a simple checker (an object which implements
-IChecker) to hold valid user/password pairs. The checker
-gets registered with the portal, so it knows who to ask when new
-clients connect. We use a checker named
-InMemoryUsernamePasswordDatabaseDontUse, which suggests
-that 1: all the username/password pairs are kept in memory instead of
-being saved to a database or something, and 2: you shouldn't use
-it. The admonition against using it is because there are better
-schemes: keeping everything in memory will not work when you have
-thousands or millions of users to keep track of, the passwords will be
-stored in the .tap file when the application shuts down (possibly a
-security risk), and finally it is a nuisance to add or remove users
-after the checker is constructed.
+Fourth, we made a simple checker (an object which
+implements IChecker) to hold valid user/password
+pairs. The checker gets registered with the portal, so it knows who to
+ask when new clients connect. We use a checker
+named InMemoryUsernamePasswordDatabaseDontUse, which
+suggests that 1: all the username/password pairs are kept in memory
+instead of being saved to a database or something, and 2: you
+shouldn't use it. The admonition against using it is because there are
+better schemes: keeping everything in memory will not work when you
+have thousands or millions of users to keep track of, the passwords
+will be stored in the .tap file when the application shuts down
+(possibly a security risk), and finally it is a nuisance to add or
+remove users after the checker is constructed.
Fifth, we create a pb.PBServerFactory to listen on a TCP
port. This factory knows how to connect the remote client to the Portal, so
@@ -554,22 +574,23 @@ protocols (non-PB) would do something similar: the factory that creates
Protocol objects will give those objects access to the Portal so
authentication can take place.
-On the client side, a pb.PBClientFactory is created (as before) and attached to a TCP connection. When the
-connection completes, the factory will be asked to produce a Protocol, and
-it will create a PB object. Unlike the previous chapter, where we used
-.getRootObject, here we use factory.login to
-initiate the cred authentication process. We provide a
-credentials object, which is the client-side agent for doing
-our half of the authentication process. This process may involve several
-messages: challenges, responses, encrypted passwords, secure hashes, etc. We
-give our credentials object everything it will need to respond correctly (in
-this case, a username and password, but you could write a credential that
-used public-key encryption or even fancier techniques).
-
-login returns a Deferred which, when it fires, will return a
-pb.RemoteReference to the remote avatar. We can then do
-callRemote to invoke a perspective_foo method on
+
On the client side, a pb.PBClientFactory is created
+(as before) and attached to a TCP
+connection. When the connection completes, the factory will be asked
+to produce a Protocol, and it will create a PB object. Unlike the
+previous chapter, where we used .getRootObject, here we
+use factory.login to initiate the cred authentication
+process. We provide a credentials object, which is the
+client-side agent for doing our half of the authentication
+process. This process may involve several messages: challenges,
+responses, encrypted passwords, secure hashes, etc. We give our
+credentials object everything it will need to respond correctly (in
+this case, a username and password, but you could write a credential
+that used public-key encryption or even fancier techniques).
+
+login returns a Deferred which, when it fires, will
+return a pb.RemoteReference to the remote avatar. We can
+then do callRemote to invoke a perspective_foo method on
that Avatar.
@@ -578,19 +599,23 @@ that Avatar.
pbAnonServer.py
pbAnonClient.py
-pbAnonServer.py implements a server based on pb6server.py, extending it to
-permit anonymous logins in addition to authenticated logins. A
-AllowAnonymousAccess
-checker and a
-InMemoryUsernamePasswordDatabaseDontUse checker are registered and the
-client's choice of credentials object determines which is used to authenticate
-the login. In either case, the realm will be called on to create an avatar for
-the login. AllowAnonymousAccess always produces an avatarId
- of ANONYMOUS.
-
-On the client side, the only change is the use of an instance of
-Anonymous when calling
-PBClientFactory.login.
+pbAnonServer.py implements a server based on pb6server.py,
+extending it to permit anonymous logins in addition to authenticated
+logins. A AllowAnonymousAccess checker and
+a
+InMemoryUsernamePasswordDatabaseDontUse checker are registered
+and the client's choice of credentials object determines which is used
+to authenticate the login. In either case, the realm will be called
+on to create an avatar for the
+login. AllowAnonymousAccess always produces
+an avatarId of ANONYMOUS.
+
+On the client side, the only change is the use of an instance
+of Anonymous
+when calling PBClientFactory.login.
Using Avatars
@@ -619,10 +644,11 @@ be described in more detail below.
Making Avatars
-In the example above, we create Avatars upon request, during
-requestAvatar. Depending upon the service, these Avatars might
-already exist before the connection is received, and might outlive the
-connection. The Avatars might also accept multiple connections.
+In the example above, we create Avatars upon request,
+during requestAvatar. Depending upon the service, these
+Avatars might already exist before the connection is received, and
+might outlive the connection. The Avatars might also accept multiple
+connections.
Another possibility is that the Avatars might exist ahead of time, but in
a different form (frozen in a pickle and/or saved in a database). In this
@@ -631,8 +657,8 @@ then do something with the result before it can provide an avatar. In this
case, it would probably return a Deferred so it could provide the real
Avatar later, once the lookup had completed.
-Here are some possible implementations of
-MyRealm.requestAvatar:
+Here are some possible implementations
+of MyRealm.requestAvatar:
# pre-existing, static avatars
@@ -690,12 +716,12 @@ something in the server, and if there are clients attached, it should update
them (through the mind
argument which lets the Avatar do callRemote
on the client).
-One common idiom which accomplishes this is to have the Realm tell the
-avatar that a remote client has just attached. The Realm can also ask the
-protocol to let it know when the connection goes away, so it can then inform
-the Avatar that the client has detached. The third member of the
-requestAvatar return tuple is a callable which will be invoked
-when the connection is lost.
+One common idiom which accomplishes this is to have the Realm tell
+the avatar that a remote client has just attached. The Realm can also
+ask the protocol to let it know when the connection goes away, so it
+can then inform the Avatar that the client has detached. The third
+member of the requestAvatar return tuple is a callable
+which will be invoked when the connection is lost.
class MyPerspective(pb.Avatar):
@@ -722,16 +748,17 @@ class MyRealm:
Viewable
-Once you have IPerspective objects (i.e. the Avatar) to
-represent users, the Viewable class can come into play. This
-class behaves a lot like Referenceable: it turns into a
-RemoteReference when sent over the wire, and certain methods
-can be invoked by the holder of that reference. However, the methods that
-can be called have names that start with view_ instead of
-remote_, and those methods are always called with an extra
-perspective argument that points to the Avatar through which
-the reference was sent:
+Once you have IPerspective objects (i.e. the Avatar)
+to represent users, the Viewable class can come into
+play. This class behaves a lot like Referenceable: it
+turns into a RemoteReference when sent over the wire, and
+certain methods can be invoked by the holder of that
+reference. However, the methods that can be called have names that
+start with view_ instead of remote_, and
+those methods are always called with an extra perspective
+argument that points to the Avatar through which the reference was
+sent:
class Foo(pb.Viewable):
@@ -745,13 +772,14 @@ the same object. The view_ methods can use the
gives them a way to do additional permission checks, do per-user accounting,
etc.
-This is the shortcut which makes per-user-per-group capability objects
-much easier to use. Instead of creating such per-(user,group) objects, you
-just have per-group objects which inherit from pb.Viewable, and
-give the user references to them. The local pb.Avatar object
-will automatically show up as the perspective
argument in the
-view_* method calls, give you a chance to involve the Avatar in
-the process.
+This is the shortcut which makes per-user-per-group capability
+objects much easier to use. Instead of creating such per-(user,group)
+objects, you just have per-group objects which inherit
+from pb.Viewable, and give the user references to
+them. The local pb.Avatar object will automatically show
+up as the perspective
argument in the view_*
+method calls, give you a chance to involve the Avatar in the
+process.
Chat Server with Avatars
@@ -764,14 +792,16 @@ be available for a game next saturday afternoon).
chatserver.py
-Notice that the client uses perspective_joinGroup to both
-join a group and retrieve a RemoteReference to the
-Group object. However, the reference they get is actually to a
-special intermediate object called a pb.ViewPoint. When they do
-group.callRemote("send", "message"), their avatar is inserted
-into the argument list that Group.view_send actually sees. This
-lets the group get their username out of the Avatar without giving the
-client an opportunity to spoof someone else.
+Notice that the client uses perspective_joinGroup to
+both join a group and retrieve a RemoteReference to
+the Group object. However, the reference they get is
+actually to a special intermediate object called
+a pb.ViewPoint. When they
+do group.callRemote("send", "message"), their avatar is
+inserted into the argument list that Group.view_send
+actually sees. This lets the group get their username out of the
+Avatar without giving the client an opportunity to spoof someone
+else.
The client side code that joins a group and sends a message would look
like this:
diff --git a/doc/core/howto/pb-intro.xhtml b/doc/core/howto/pb-intro.xhtml
index 6d976c8..2350830 100644
--- a/doc/core/howto/pb-intro.xhtml
+++ b/doc/core/howto/pb-intro.xhtml
@@ -55,13 +55,13 @@ out through their interaction than explaining them one at a time.
- Factory
+ Factory
: internet/protocol.pyPBServerFactory
+ PBServerFactory
: spread/pb.pyBroker
+ Broker
: spread/pb.py
@@ -70,15 +70,15 @@ out through their interaction than explaining them one at a time.
- -
RemoteReference
+ RemoteReference
: spread/pb.py -
pb.Root
+ pb.Root
: spread/pb.py, actually defined as
twisted.spread.flavors.Root
in spread/flavors.py -
pb.Referenceable
+ pb.Referenceable
: spread/pb.py, actually defined as
twisted.spread.flavors.Referenceable
in spread/flavors.py
- Portal
+ Portal
: cred/portal.pyIRealm
+ IRealm
: cred/portal.pyIPerspective
+ IPerspective
: spread/pb.py, which you will usually be interacting
with via pb.Avatar (a basic implementor of the interface).
@@ -205,11 +205,11 @@ published methods with the appropriate prefix.
In addition to returning objects that you can call remote methods on, you
can return structured copies of local objects.
-There are 2 basic flavors that allow for copying objects remotely. Again,
-you can use these by subclassing them. In order to specify what state you want
-to have copied when these are serialized, you can either use the Python default
-__getstate__ or specialized method calls for that
-flavor.
+There are 2 basic flavors that allow for copying objects remotely.
+Again, you can use these by subclassing them. In order to specify
+what state you want to have copied when these are serialized, you can
+either use the Python default __getstate__
+or specialized method calls for that flavor.
diff --git a/doc/core/howto/pb-limits.xhtml b/doc/core/howto/pb-limits.xhtml
index f0e6204..24b49c8 100644
--- a/doc/core/howto/pb-limits.xhtml
+++ b/doc/core/howto/pb-limits.xhtml
@@ -30,11 +30,12 @@ limit is 640 * 1024, defined by twisted.spread.banana.SIZE_LIMIT.
It's possible to raise this limit by changing this value (but take care to
change it on both sides of the connection).
- Another limit imposed by Twisted's Banana implementation is a limit on
-the size of long integers. The purpose of this limit is the same as the
-SIZE_LIMIT. By default, only integers between -2 ** 448 and 2
-** 448 (exclusive) can be transferred. This limit can be changed using
-twisted.spread.banana.setPrefixLimit.
+ Another limit imposed by Twisted's Banana implementation is a
+limit on the size of long integers. The purpose of this limit is the
+same as the SIZE_LIMIT. By default, only integers
+between -2 ** 448 and 2 ** 448 (exclusive) can be transferred. This
+limit can be changed
+using twisted.spread.banana.setPrefixLimit.
Perspective Broker Limits
diff --git a/doc/core/howto/pb-usage.xhtml b/doc/core/howto/pb-usage.xhtml
index c602e8a..924f9ab 100644
--- a/doc/core/howto/pb-usage.xhtml
+++ b/doc/core/howto/pb-usage.xhtml
@@ -9,47 +9,49 @@
Basic Example
-The first example to look at is a complete (although somewhat trivial)
-application. It uses PBServerFactory() on the server side, and
-PBClientFactory() on the client side.
+The first example to look at is a complete (although somewhat
+trivial) application. It uses PBServerFactory() on the
+server side, and PBClientFactory() on the client
+side.
pbsimple.py
pbsimpleclient.py
-First we look at the server. This defines an Echoer class (derived from
-pb.Root), with a method called
-remote_echo().
-pb.Root objects (because of
-their inheritance of
-pb.Referenceable, described
-later) can define methods with names of the form remote_*; a
-client which obtains a remote reference to that
-pb.Root object will be able to
-invoke those methods.
-
-The pb.Root-ish object is
-given to a pb.PBServerFactory(). This is a
-Factory object like
-any other: the Protocol objects it creates for new
-connections know how to speak the PB protocol. The object you give to
-pb.PBServerFactory() becomes the root object
, which
-simply makes it available for the client to retrieve. The client may only
-request references to the objects you want to provide it: this helps you
-implement your security model. Because it is so common to export just a
-single object (and because a remote_* method on that one can
-return a reference to any other object you might want to give out), the
+
First we look at the server. This defines an Echoer class (derived
+from pb.Root), with a
+method called remote_echo(). pb.Root objects (because of their
+inheritance of pb.Referenceable, described later) can
+define methods with names of the form remote_*; a client
+which obtains a remote reference to that pb.Root object will be able to invoke
+those methods.
+
+The pb.Root-ish
+object is given to a pb.PBServerFactory(). This
+is a Factory
+object like any other: the Protocol objects it creates
+for new connections know how to speak the PB protocol. The object you
+give to pb.PBServerFactory() becomes the root
+object
, which simply makes it available for the client to
+retrieve. The client may only request references to the objects you
+want to provide it: this helps you implement your security
+model. Because it is so common to export just a single object (and
+because a remote_* method on that one can return a
+reference to any other object you might want to give out), the
simplest example is one where the PBServerFactory is given the root object, and
-the client retrieves it.
+base="twisted.spread.pb">PBServerFactory is given the root
+object, and the client retrieves it.
-The client side uses
-pb.PBClientFactory to make a
-connection to a given port. This is a two-step process involving opening
-a TCP connection to a given host and port and requesting the root object
+
The client side uses pb.PBClientFactory to make a connection
+to a given port. This is a two-step process involving opening a TCP
+connection to a given host and port and requesting the root object
using .getRootObject().
Because .getRootObject() has to wait until a network
@@ -61,8 +63,8 @@ base="twisted.internet.defer">Deferreds). If and when the
connection succeeds and a reference to the remote root object is
obtained, this callback is run. The first argument passed to the
callback is a remote reference to the distant root object. (you can
-give other arguments to the callback too, see the other parameters for
-.addCallback() and .addCallbacks()).
+give other arguments to the callback too, see the other parameters
+for .addCallback() and .addCallbacks()).
The callback does:
@@ -70,15 +72,17 @@ give other arguments to the callback too, see the other parameters for
object.callRemote("echo", "hello network")
-which causes the server's .remote_echo() method to be invoked.
-(running .callRemote("boom") would cause
-.remote_boom() to be run, etc). Again because of the delay
-involved, callRemote() returns a
-Deferred. Assuming the
-remote method was run without causing an exception (including an attempt to
-invoke an unknown method), the callback attached to that
-Deferred will be
-invoked with any objects that were returned by the remote method call.
+which causes the server's .remote_echo() method to be
+invoked. (running .callRemote("boom") would
+cause .remote_boom() to be run, etc). Again because of
+the delay involved, callRemote() returns
+aDeferred. Assuming the remote
+method was run without causing an exception (including an attempt to
+invoke an unknown method), the callback attached to
+that Deferred
+will be invoked with any objects that were returned by the remote
+method call.
In this example, the server's Echoer object has a method
invoked, exactly as if some code on the server side had done:
@@ -100,54 +104,58 @@ local. Trying to do so (as some other RPC mechanisms do, coughCORBAcough)
breaks down when faced with the asynchronous nature of the network. Using
Deferreds turns out to be a very clean way to deal with the whole thing.
-The remote reference object (the one given to
-getRootObject()'s success callback) is an instance the RemoteReference class. This means
-you can use it to invoke methods on the remote object that it refers to. Only
-instances of RemoteReference are eligible for
-.callRemote(). The RemoteReference object is the one that lives
-on the remote side (the client, in this case), not the local side (where the
-actual object is defined).
-
-In our example, the local object is that Echoer() instance,
-which inherits from pb.Root,
-which inherits from
-pb.Referenceable. It is that
-Referenceable class that makes the object eligible to be available
-for remote method callsThere are a few other classes
-that can bestow this ability, but pb.Referenceable is the easiest to
-understand; see 'flavors' below for details on the others.. If you have
-an object that is Referenceable, then any client that manages to get a
-reference to it can invoke any remote_* methods they please.
+The remote reference object (the one given
+to getRootObject()'s success callback) is an instance
+the RemoteReference
+class. This means you can use it to invoke methods on the remote
+object that it refers to. Only instances of RemoteReference are eligible
+for .callRemote(). The RemoteReference object is the one that
+lives on the remote side (the client, in this case), not the local
+side (where the actual object is defined).
+
+In our example, the local object is that Echoer()
+instance, which inherits from pb.Root, which inherits
+from pb.Referenceable. It is
+that Referenceable class that makes the object eligible
+to be available for remote method callsThere
+are a few other classes that can bestow this ability, but
+pb.Referenceable is the easiest to understand; see 'flavors' below for
+details on the others.. If you have an object that is
+Referenceable, then any client that manages to get a reference to it
+can invoke any remote_* methods they please.
-The only thing they can do is invoke those
-methods. In particular, they cannot access attributes. From a security point
-of view, you control what they can do by limiting what the
-remote_* methods can do.
-
-Also note: the other classes like
-Referenceable allow access to
-other methods, in particular perspective_* and view_*
-may be accessed. Don't write local-only methods with these names, because then
-remote callers will be able to do more than you intended.
-
-Also also note: the other classes like
-pb.Copyable do allow
-access to attributes, but you control which ones they can see.
+The only thing they can do is invoke those methods. In
+particular, they cannot access attributes. From a security point of
+view, you control what they can do by limiting what
+the remote_* methods can do.
+
+Also note: the other classes like Referenceable allow access to other
+methods, in particular perspective_*
+and view_* may be accessed. Don't write local-only
+methods with these names, because then remote callers will be able to
+do more than you intended.
+
+Also also note: the other classes like pb.Copyable do allow access to
+attributes, but you control which ones they can see.
-You don't have to be a
-pb.Root to be remotely callable,
-but you do have to be
-pb.Referenceable. (Objects that
-inherit from pb.Referenceable
-but not from pb.Root can be
-remotely called, but only
-pb.Root-ish objects can be given
-to the PBServerFactory.)
+You don't have to be a pb.Root to be remotely callable, but you
+do have to be pb.Referenceable. (Objects that inherit
+from pb.Referenceable
+but not from pb.Root
+can be remotely called, but only pb.Root-ish objects can be given to
+the PBServerFactory.)
Complete Example
@@ -166,11 +174,11 @@ base="twisted.spread">pb.PBClientFactory.getRootObject will
handle all the details of waiting for the creation of a connection.
It returns a Deferred, which will have its
-callback called when the reactor connects to the remote server and
-pb.PBClientFactory gets the
-root, and have its errback called when the
-object-connection fails for any reason, whether it was host lookup
-failure, connection refusal, or some server-side error.
+callback called when the reactor connects to the remote server
+and pb.PBClientFactory
+gets the root, and have its errback called
+when the object-connection fails for any reason, whether it was host
+lookup failure, connection refusal, or some server-side error.
The root object has a method called remote_getTwo, which
@@ -194,34 +202,36 @@ class="python">callback or errback
will be made, depending on whether an error occurred in processing the
method call.
-You can use this technique to provide access to arbitrary sets of objects.
-Just remember that any object that might get passed over the wire
must
-inherit from Referenceable
-(or one of the other flavors). If you try to pass a non-Referenceable object
-(say, by returning one from a remote_* method), you'll get an
-InsecureJelly
-exceptionThis can be overridden, by subclassing one of
-the Serializable flavors and defining custom serialization code for your
-class. See Passing Complex Types for
-details..
+You can use this technique to provide access to arbitrary sets of
+objects. Just remember that any object that might get passed over
+the wire
must inherit from Referenceable (or one of the other
+flavors). If you try to pass a non-Referenceable object (say, by
+returning one from a remote_* method), you'll get
+an InsecureJelly
+exceptionThis can be overridden, by subclassing
+one of the Serializable flavors and defining custom serialization code
+for your class. See Passing Complex
+Types for details..
References can come back to you
-If your server gives a reference to a client, and then that client gives
-the reference back to the server, the server will wind up with the same
-object it gave out originally. The serialization layer watches for returning
-reference identifiers and turns them into actual objects. You need to stay
-aware of where the object lives: if it is on your side, you do actual method
-calls. If it is on the other side, you do
-.callRemote()The binary nature of this
-local vs. remote scheme works because you cannot give RemoteReferences to a
-third party. If you could, then your object A could go to B, B could give it to
-C, C might give it back to you, and you would be hard pressed to tell if the
-object lived in C's memory space, in B's, or if it was really your own object,
-tarnished and sullied after being handed down like a really ugly picture that
-your great aunt owned and which nobody wants but which nobody can bear to throw
-out. Ok, not really like that, but you get the idea..
+If your server gives a reference to a client, and then that client
+gives the reference back to the server, the server will wind up with
+the same object it gave out originally. The serialization layer
+watches for returning reference identifiers and turns them into actual
+objects. You need to stay aware of where the object lives: if it is on
+your side, you do actual method calls. If it is on the other side, you
+do .callRemote()The binary nature
+of this local vs. remote scheme works because you cannot give
+RemoteReferences to a third party. If you could, then your object A
+could go to B, B could give it to C, C might give it back to you, and
+you would be hard pressed to tell if the object lived in C's memory
+space, in B's, or if it was really your own object, tarnished and
+sullied after being handed down like a really ugly picture that your
+great aunt owned and which nobody wants but which nobody can bear to
+throw out. Ok, not really like that, but you get the idea..
pb2server.py
pb2client.py
@@ -277,20 +287,21 @@ object.
about when they go wrong? The Python Way is to raise an exception of some
sort. The Twisted Way is the same.
-The only special thing you do is to define your Exception
-subclass by deriving it from pb.Error. When any remotely-invokable method
-(like remote_* or perspective_*) raises a
-pb.Error-derived exception, a serialized form of that Exception
-object will be sent back over the wireTo be precise,
-the Failure will be sent if any exception is raised, not just
-pb.Error-derived ones. But the server will print ugly error messages if you
-raise ones that aren't derived from pb.Error.. The other side (which
-did callRemote) will have the errback
-callback run with a Failure object that contains a copy of
-the exception object. This Failure object can be queried to
-retrieve the error message and a stack traceback.
+The only special thing you do is to define
+your Exception subclass by deriving it
+from pb.Error. When any
+remotely-invokable method (like remote_*
+or perspective_*) raises a pb.Error-derived
+exception, a serialized form of that Exception object will be sent
+back over the wireTo be precise, the Failure
+will be sent if any exception is raised, not just
+pb.Error-derived ones. But the server will print ugly error messages
+if you raise ones that aren't derived from pb.Error.. The other
+side (which did callRemote) will have
+the errback
callback run with a Failure object that contains a
+copy of the exception object. This Failure object can be
+queried to retrieve the error message and a stack traceback.
Failure is a
special class, defined in twisted/python/failure.py, created to
@@ -299,15 +310,16 @@ can be nested, errback functions can be chained. If one errback
can't handle the particular type of failure, it can be passed along
to a
errback handler further down the chain.
-For simple purposes, think of the Failure as just a container
-for remotely-thrown Exception objects. To extract the string that
-was put into the exception, use its .getErrorMessage() method.
-To get the type of the exception (as a string), look at its
-.type attribute. The stack traceback is available too. The
-intent is to let the errback function get just as much information about the
-exception as Python's normal try: clauses do, even though the
-exception occurred in somebody else's memory space at some unknown time in
-the past.
+For simple purposes, think of the Failure as just a
+container for remotely-thrown Exception objects. To
+extract the string that was put into the exception, use
+its .getErrorMessage() method. To get the type of the
+exception (as a string), look at its .type attribute. The
+stack traceback is available too. The intent is to let the errback
+function get just as much information about the exception as Python's
+normal try: clauses do, even though the exception
+occurred in somebody else's memory space at some unknown time in the
+past.
exc_server.py
exc_client.py
@@ -321,53 +333,56 @@ got remote Exception
Main loop terminated.
-Oh, and what happens if you raise some other kind of exception? Something
-that isn't subclassed from pb.Error? Well, those are
-called unexpected exceptions
, which make Twisted think that something
-has really gone wrong. These will raise an exception on the
-server side. This won't break the connection (the exception is
-trapped, just like most exceptions that occur in response to network
-traffic), but it will print out an unsightly stack trace on the server's
-stderr with a message that says Peer Will Receive PB Traceback
, just
-as if the exception had happened outside a remotely-invokable method. (This
-message will go the current log target, if log.startLogging was used to redirect it). The
-client will get the same Failure object in either case, but
-subclassing your exception from pb.Error is the way to tell
-Twisted that you expect this sort of exception, and that it is ok to just
-let the client handle it instead of also asking the server to complain. Look
-at exc_client.py and change it to invoke broken2()
-instead of broken() to see the change in the server's
-behavior.
-
-If you don't add an errback function to the Deferred, then a remote
-exception will still send a Failure object back over, but it
-will get lodged in the Deferred with nowhere to go. When that
-Deferred finally goes out of scope, the side that did
-callRemote will emit a message about an Unhandled error in
-Deferred
, along with an ugly stack trace. It can't raise an exception at
-that point (after all, the callRemote that triggered the
-problem is long gone), but it will emit a traceback. So be a good programmer
-and always add errback handlers, even if they are just
-calls to log.err.
+Oh, and what happens if you raise some other kind of exception?
+Something that isn't subclassed from pb.Error?
+Well, those are called unexpected exceptions
, which make
+Twisted think that something has really gone wrong. These
+will raise an exception on the server side. This won't break
+the connection (the exception is trapped, just like most exceptions
+that occur in response to network traffic), but it will print out an
+unsightly stack trace on the server's stderr with a message that
+says Peer Will Receive PB Traceback
, just as if the exception
+had happened outside a remotely-invokable method. (This message will
+go the current log target, if log.startLogging was used to redirect
+it). The client will get the same Failure object in
+either case, but subclassing your exception from pb.Error
+is the way to tell Twisted that you expect this sort of exception, and
+that it is ok to just let the client handle it instead of also asking
+the server to complain. Look at exc_client.py and change
+it to invoke broken2() instead of broken()
+to see the change in the server's behavior.
+
+If you don't add an errback function to
+the Deferred,
+then a remote exception will still send a Failure object
+back over, but it will get lodged in the Deferred with
+nowhere to go. When that Deferred finally goes out of
+scope, the side that did callRemote will emit a message
+about an Unhandled error in Deferred
, along with an ugly stack
+trace. It can't raise an exception at that point (after all,
+the callRemote that triggered the problem is long gone),
+but it will emit a traceback. So be a good programmer and always
+add errback handlers, even if they are just calls
+to log.err.
Try/Except blocks and Failure.trap
-To implement the equivalent of the Python try/except blocks (which can
-trap particular kinds of exceptions and pass others up
to
-higher-level try/except blocks), you can use the
-.trap() method in conjunction with multiple
-errback handlers on the Deferred. Re-raising an
-exception in an errback handler serves to pass that new
-exception to the next handler in the chain. The trap method is
-given a list of exceptions to look for, and will re-raise anything that
-isn't on the list. Instead of passing unhandled exceptions up
to an
+
To implement the equivalent of the Python try/except blocks (which
+can trap particular kinds of exceptions and pass others up
to
+higher-level try/except blocks), you can use
+the .trap() method in conjunction with
+multiple errback handlers on
+the Deferred. Re-raising an exception in
+an errback handler serves to pass that new exception to
+the next handler in the chain. The trap method is given a
+list of exceptions to look for, and will re-raise anything that isn't
+on the list. Instead of passing unhandled exceptions up
to an
enclosing try block, this has the effect of passing the
-exception off
to later errback handlers on the same
-Deferred. The trap calls are used in chained
-errbacks to test for each kind of exception in sequence.
+exception off
to later errback handlers on the
+same Deferred. The trap calls are used in
+chained errbacks to test for each kind of exception in sequence.
trap_server.py
trap_client.py
@@ -396,60 +411,67 @@ living, breathing instance of some class): one reason is that it does not
know which local class ought to be used to create an instance that
corresponds to the remote objectThe naive approach of simply doing import
-SomeClass to match a remote caller who claims to have an object of
-type SomeClass
could have nasty consequences for some modules that do
-significant operations in their __init__ methods (think
-telnetlib.Telnet(host='localhost', port='chargen'), or even
-more powerful classes that you have available in your server program).
-Allowing a remote entity to create arbitrary classes in your namespace is
-nearly equivalent to allowing them to run arbitrary code.
+-->The naive approach of simply
+doing import SomeClass to match a remote caller who
+claims to have an object of type SomeClass
could have nasty
+consequences for some modules that do significant operations in
+their __init__ methods
+(think telnetlib.Telnet(host='localhost',
+port='chargen'), or even more powerful classes that you have
+available in your server program). Allowing a remote entity to create
+arbitrary classes in your namespace is nearly equivalent to allowing
+them to run arbitrary code.
The pb.InsecureJelly
-exception arises because the class being sent over the wire has not been
-registered with the serialization layer (known as jelly). The easiest way to make it possible to
-copy entire class instances over the wire is to have them inherit from pb.Copyable, and then to use
-setUnjellyableForClass(remoteClass, localClass) on the
-receiving side. See Passing Complex Types
-for an example.
.
-
-The receiving end of the connection gets to decide what to accept and what
-to reject. It indicates its disapproval by raising a pb.InsecureJelly exception. Because it occurs
-at the remote end, the exception is returned to the caller asynchronously,
-so an errback handler for the associated Deferred
-is run. That errback receives a Failure which wraps the
-InsecureJelly.
-
-
-Remember that trap re-raises exceptions that it wasn't asked
-to look for. You can only check for one set of exceptions per errback
-handler: all others must be checked in a subsequent handler.
-check_MyException shows how multiple kinds of exceptions can be
-checked in a single errback: give a list of exception types to
-trap, and it will return the matching member. In this case, the
-kinds of exceptions we are checking for (MyException and
-MyOtherException) may be raised by the remote end: they inherit
-from pb.Error.
-
-The handler can return None to terminate processing of the
-errback chain (to be precise, it switches to the callback that follows the
-errback; if there is no callback then processing terminates). It is a good
-idea to put an errback that will catch everything (no trap
-tests, no possible chance of raising more exceptions, always returns
-None) at the end of the chain. Just as with regular try:
-except: handlers, you need to think carefully about ways in which
-your errback handlers could themselves raise exceptions. The extra
-importance in an asynchronous environment is that an exception that falls
-off the end of the Deferred will not be signalled until that
-Deferred goes out of scope, and at that point may only cause a
-log message (which could even be thrown away if log.startLogging is not used to point it at
-stdout or a log file). In contrast, a synchronous exception that is not
-handled by any other except: block will very visibly terminate
-the program immediately with a noisy stack trace.
+exception arises because the class being sent over the wire has not
+been registered with the serialization layer (known
+as jelly). The easiest
+way to make it possible to copy entire class instances over the wire
+is to have them inherit from pb.Copyable, and then to
+use setUnjellyableForClass(remoteClass, localClass) on
+the receiving side. See Passing Complex
+Types for an example..
+
+The receiving end of the connection gets to decide what to accept and
+what to reject. It indicates its disapproval by raising
+a pb.InsecureJelly
+exception. Because it occurs at the remote end, the exception is
+returned to the caller asynchronously, so an errback
+handler for the associated Deferred is run. That errback
+receives a Failure which wraps
+the InsecureJelly.
+
+
+Remember that trap re-raises exceptions that it wasn't
+asked to look for. You can only check for one set of exceptions per
+errback handler: all others must be checked in a subsequent
+handler. check_MyException shows how multiple kinds of
+exceptions can be checked in a single errback: give a list of
+exception types to trap, and it will return the matching
+member. In this case, the kinds of exceptions we are checking for
+(MyException and MyOtherException) may be
+raised by the remote end: they inherit from pb.Error.
+
+The handler can return None to terminate processing of
+the errback chain (to be precise, it switches to the callback that
+follows the errback; if there is no callback then processing
+terminates). It is a good idea to put an errback that will catch
+everything (no trap tests, no possible chance of raising
+more exceptions, always returns None) at the end of the
+chain. Just as with regular try: except: handlers, you
+need to think carefully about ways in which your errback handlers
+could themselves raise exceptions. The extra importance in an
+asynchronous environment is that an exception that falls off the end
+of the Deferred will not be signalled until
+that Deferred goes out of scope, and at that point may
+only cause a log message (which could even be thrown away
+if log.startLogging is
+not used to point it at stdout or a log file). In contrast, a
+synchronous exception that is not handled by any
+other except: block will very visibly terminate the
+program immediately with a noisy stack trace.
callFour shows another kind of exception that can occur
while using callRemote: try: except pb.DeadReferenceError block.
Yet another kind that can occur is a pb.PBConnectionLost exception. This occurs
-(asynchronously) if the connection was lost while you were waiting for a
-callRemote call to complete. When the line goes dead, all
-pending requests are terminated with this exception. Note that you have no
-way of knowing whether the request made it to the other end or not, nor how
-far along in processing it they had managed before the connection was
-lost. XXX: explain transaction semantics, find a decent reference.
+base="twisted.spread">pb.PBConnectionLost exception. This
+occurs (asynchronously) if the connection was lost while you were
+waiting for a callRemote call to complete. When the line
+goes dead, all pending requests are terminated with this
+exception. Note that you have no way of knowing whether the request
+made it to the other end or not, nor how far along in processing it
+they had managed before the connection was lost. XXX: explain
+transaction semantics, find a decent reference.