From Croquet Consortium

Contents 1 LAN 2 WAN 3 Port Usage - The Dispatcher 4 Discovery 5 Performance 6 Additional Technical Information

LAN

All of the demos except one (KAT) will work automatically on a LAN without any pre-arrangement. The "Master" that starts up first broadcasts itself on the LAN. Everyone else will find it.

This is accomplished by having the Master broadcast it's location on the LAN.

WAN

There are two examples in the SDK that reach wider:

• Starting the SimpleDemo creates a router with one world on it, and provides a tool (Tools->What's My Location) that displays information including "Postcard as XML", which is a text serialization of the connection information for this router, and which can be sent via mail, text chat, etc. Another user can paste that into Tools->Connect to Another World in order to connect across the WAN. On the one host machine, you will need to make the operating-system selected port available to the Internet.

• The KAT demo prompts at startup for a fixed IP address to connect to. The default is an experimental server we maintain that has a router with several worlds. Or you can enter an empty string and it will start it's own router and worlds on your machine, similarly to SimpleDemo. If you tell that address to others, they can type it in and connect to you. On the one host machine, you will need to make port 5910 available to the Internet.

Port Usage - The Dispatcher

A "dispatcher" runs a single port shared by one or more "routers." In all the different examples, this is the one thing that participants have to be able to reach. The participants connect to the dispatcher, not vice versa, so a participant's firewall just needs to be allow an "outbound" connection. The port on the dispatcher doesn't care if connecting participants are on the same subnet or not.

Most of the demos ask the operating system for any available socket allocation, which gives an unpredictable port number. The KAT gives an example of specifying a specific port through code, although the default is 5910.

The socket and the code that uses it is straightforward -- there's nothing built-in for punching through firewalls and such. There have been lab versions of Croquet that used hole-punching, and they worked fine in the lab! :-)

Discovery

How does a harness discover the address:port of the dispatcher/router for a given island ID?

• SimpleDemoMaster (if I recall correctly) codes the router address:port in the TPostcard. It gives an example of a UI that displays to the user an XML-serialized form of this information, which you can send out-of-band to other folks (e.g., in email) so that they can create a TPostcard with the right information. Thus it is "do it yourself discovery," and has no limitations on different subnets, etc.

• BFDMaster/Participant and CroquetMaster/Participant give an example where a participant running a router (a so-called "master") broadcasts its island ID and address:port to the local subnet. The machinery for broadcasting and keeping track of this mapping is TContactPoint. Thus it is a "dynamic registry that automatically keeps itself up to date for a subnet."

• KCroquetParticipant prompts for a single dispatcher address and then populates the TContactPoint with information on a known set of island IDs using this address and hardcoded port. Thus it is a "fixed registry with a pluggable address," and has no limitations on different subnets, etc. Future work plans modify this to use a repository to supply the map of island ID's to current distributor address:ports.

There is already A Preliminary Directory of Public Croquet Spaces. Future work plans for the Croquet Collaborative are to use a meta island to maintain an ID-to-distributor map. This would initially be similar to the global media cache already implemented, but would eventually diverge in implementation based on being slowly-changing and much smaller rather than having large and immutable data, and needing to be auditable rather than potentially censorship-resistant.

Performance

The above just describes connectivity. Performance matters a lot more on WAN than LAN.

The code in the repositories has not been tuned. (Commercial applications might well be.) Even as is, my experience with the public code is that WAN performance from my home is limited by my crummy ISP thottling my upload bandwidth to 30 KB/s. I hit that limit sending live audio and video, until I spent a few hours tuning the KAT and putting in some simple automatic adjustments. See http://www.wetmachine.com/item/685 and http://www.nabble.com/Re%3A-driving-me-crazy-tf2872513.html#a8075618

Additional Technical Information

Each harness maintains a list of islands by name and by islandID. I think of islandID as being authoritative, and name as being symbolic (with the possibility of application-specific indirection, although I don't think there's anything in the code that leverages such indirection).

The stable pointer into an island -- which can be stored in other islands (e.g., in portals) -- is a Postcard. There is a pattern that appears in a couple of places in the code where:

 #findIslandByPostcard: looks up an already processed island by name and ID, else
 #findContactByPostcard: -- which might be better named findIslandByPostcardViaContact:.

Given this framework, there are a couple of different approaches that can be taken.

• For example, you could hardcode the router address:port into the Postcard and hardcode the join process in #findContactByPostcard:. (See the demos that use CroquetHarnessWithMenu.)

• The KAT delegates to to a Contact to resolve and join with the router for each specific name/ID. (The Contact then delegates to a ConnectionStrategy to manage the join process, including reconnection as necessary.)

• The other demos use a strategy midway between these two.

For those demos that use Contacts, how are the Contacts created? There's a map of name/ID to Contact called a ContactPoint. (I don't know the origin of the name. I think of it as a "DNS"-like thing, or "Contact discovery map".) The middle-ground demos populate the ContactPoint automatically by having "Masters" broadcast their worlds on the LAN.

The KAT just hardcodes a fixed set of known worlds: each Harness explicitly creates a set of Contacts to populate the ContactPoint in KStandardHarness>>setupUser:password:entry:address:port:. The next step for KAT development is to instead start with an empty ContactPoint and have it consult a service whenever there is a request for an unknown ID.

Note that the name/ID managed by the ContactPoint has to match that created by the Router. (In order to not use lots of different IP ports, communications on multiple Routers are multiplexed through an object called a Dispatcher. The Dispatcher has a means of dynamically creating new Routers (for the requested ID), or rejecting a request to connect to a non-existent Router ID.) The KAT creates a hardcoded set of Routers with the known set of IDs. In the current KAT code, this known set of Worlds is given by KCroquetParticipant worlds (a class method). The ID for a given world is specified by the #islandID class method for the class that represents that world (e.g., the subclasses of BaseWorld). Notice that the values returned are not generated dynamically, but are hardcoded:

 TObjectID readHexFrom: '1f2f349874e53ebe785f68158591e917'

This is because the value must match up between the router on one machine and each participant on different machines. You can generate a suitable new string by print-it of TObject new, but then you paste that string into the above.

[The Dispatcher at www.croquetcollaborative.org:5910 does not dynamically create new routers for any old ID you might specify. If you try this, it just logs the attempt and disconnects you. You could imagine some extension of the protocol whereby a client could present some credentials to tell the Dispatcher to operate a new Router as a service. But the Collaborative has no plans to do this. (We don't have the bandwidth.) As I said, I would like to have the KAT have an option for any user to create their own Router on their own machine and advertise it via a service that others can use to populate their ContactPoint, but you'd still have to run your own Dispatcher/Router.]