RTMFP groups

After the initial connection to the server, a peer must be introduced to one or more peers of the same group, this technique is called “bootstrapping”. Bootstrapping allows members of the same group to see each another. After bootstrapping, the peer self-organizes into the group and meshes with the other members.

To join a group, a client must know the GroupSpecifier that defines the group. If two sets of clients use the same GroupSpecifier, and never touch, they are in separate groups. If the two groups touch, they merge into a single larger group.

Each client has a peer ID, and the peer ID space is server-specific. The peer ID is the SHA256 of the client's Diffie-Hellman public key. Both client-side and server-side ActionScript can access the peer ID as a property of each RTMFP client. Peer IDs are available in the ActionScript 3.0 NetConnection.nearID and NetConnection.farID properties. Peer IDs are also available in the Server-Side ActionScript Client.nearID and farID properties. Client-side NetConnection.nearID and server-side Client.farID share the same value. Client-side NetConnection.farID and server-side Client.nearID share the same value.

Peers within an RTMFP group can be bootstrapped in the following ways:

• Server channel automatic bootstrapping.

  When clients connect over an RTMFP connection, the server bootstraps them with peers who are members of the same NetGroup. To enable automatic bootstrapping on the client-side, set GroupSpecifier.serverChannelEnabled to true.

• Manual bootstrapping.

  To manually bootstrap peers into a mesh, call the NetGroup.addNeighbor() method.

• LAN peer discovery

  Use the GroupSpecifier class to enable LAN peer discovery. LAN peer discovery allows an RTMFP NetConnection and its NetStream and NetGroup objects to automatically locate peers and join a group on the current subnet. Peers cannot discover each other unless they’re in the same group on the same subnet of the LAN. If peers with matching groupspecs are on different subnets, no error or other event is dispatched if they fail to discover each other.

  The following code shows how to enable LAN peer discovery:

  var nc = new NetConnection(); 
  // Protocol must be RTMFP 
  nc.connect("rtmfp://fms.example.com/appname/appinstance"); 
  var gs = new GroupSpecifier("com.example.discovery-test"); 
  // Must be enabled for LAN peer discovery to work 
  gs.ipMulticastMemberUpdatesEnabled = true; 
  // Multicast address over which to exchange peer discovery. 
  gs.addIPMulticastAddress("224.0.0.255:30000"); 
  // Additional GroupSpecifier configuration... 
  var ns = new NetStream(nc, gs.toString());

Use Server-Side ActionScript to create an RTMFP NetConnection. You can connect to an application on the same server or to an application on another Flash Media Server. After you create an RTMFP NetConnection, define a GroupSpecifier to create a NetGroup and a NetStream. The server application joins the group and becomes a peer in the group mesh. A single client can join multiple groups. Once connected, you can interact with other peers in the RTMFP group. You can also publish streams into the group.

A server-side netConnection is a virtual Flash client. It has its own RTMFP stack. As far as the server is concerned, a server-side script that joins a group is the same as any client.

When a NetStream or NetGroup object is constructed with a groupspec, Flash Player displays a “Peer-assisted Networking” dialog. The dialog asks users if Flash Player can use their connection to share data with their peers.

If the user clicks “Allow for this domain”, the dialog is not displayed the next time the user connects to this application. If a user does not allow peer-assisted networking, all peer features within the group (posting, directed routing, and object replication, and multicast) are disabled. You can use RTMFP to subscribe to a pure native-IP multicast stream. In this case, the dialog is not displayed.

When using IP multicast with no peer-assisted functionality, you can disable the security dialog. Set the GroupSpecifier.peerToPeerDisabled property to true. By default, this property is false (peer-assisted connections are enabled). When peerToPeerDisabled is true, the security dialog does not appear.

Use the following ActionScript 3.0 classes and Server-Side ActionScript classes to create applications that use RTMFP groups:

• NetConnection

  Use the NetConnection class to create a two-way RTMFP connection between a Flash Player or AIR application and a Flash Media Server application. Use the RTMFP protocol in the URL you pass to the NetConnection.connect() method.

• GroupSpecifier

  Use the GroupSpecifier class to define the capabilities, restrictions, and authorizations of an RTMFP peer-to-peer group. After you define the capabilities, pass a groupspec string or a GroupSpecifier object to the NetStream and NetGroup constructors. A groupspec is an opaque string that you pass to the NetStream and NetGroup constructors.

  In server-side code, you can pass the GroupSpecifier object or a groupspec string.

  In client-side code, you can only pass a groupspec string. To generate a groupspec string, call one of the following methods: toString(), groupSpecWithAuthorizations(), and groupSpecWithoutAuthorizations().

• NetGroup

  Use the NetGroup class to manage an RTMFP group. The class properties provide information about group members. Call the class methods to post messages to the group, route messages to a group member, and to replicate objects among the group. To create a NetGroup, pass a GroupSpecifier object to the NetGroup constructor.

• NetGroupInfo

  The NetGroupInfo class specifies Quality of Service (QoS) statistics about a NetGroup object's RTMFP peer-to-peer data transport. The NetGroup.info property returns a NetGroupInfo object which is a snapshot of the current QoS state.

• NetStream

  Use the NetStream class to multicast audio and video data over a group. Pass a groupspec to the NetStream constructor and use the standard publish() and play() methods.

• NetStreamMulticastInfo

  The NetStreamMulticastInfo class specifies Quality of Service (QoS) statistics about a NetStream object's RTMFP peer-to-peer and IP multicast stream transport. The NetStream.multicastInfo property returns a NetStreamMulticastInfo object which is a snapshot of the current QoS state.

Call the NetGroup.post() method to broadcast an ActionScript message to all members of a NetGroup (also called a “group”). Use the "NetGroup.Posting.Notify" code to do something when a post has been received.

You can post messages to a group from the client-side ActionScript 3.0 NetGroup.post() method or from the Server-Side ActionScript NetGroup.post() method.

Use the post() method to broadcast non-stateful data. For example, use posting for text chat, opinion polls, and sensor reporting. Use posting to allow many clients to send small amounts of data.

This method is similar to the Server-Side ActionScript Application.broadcastMsg() method, but the post() method propagates messages from node to node in a group. Posting is not similar to using shared objects. Unlike shared objects, posting does not manage changes.

Understand the following about posting messages:

• The GroupSpecifier.postingEnabled property must be true in the groupspec passed to the NetGroup constructor.

• Receive a NetGroup.Neighbor.Connect event before you call post().

• Messages are serialized in AMF. A message can be any AMF object. A message cannot be a MovieClip.

• Messages must be unique to be considered new. Use a sequence number to make messages unique.

• Message delivery is not ordered. Message delivery is not guaranteed.

• The post() method returns the messageID for this message, or null on error. The messageID is the hexadecimal of the SHA256 of the raw bytes of the serialization of the message.

• The post() method sends a NetStatusEvent to the NetGroup's event listener with "NetGroup.Posting.Notify" in the info.code property.

 
private function OnConnect():void{ 
    StatusMessage("Connected\n"); 
    connected = true; 
    // Create a GroupSpecifier object to pass to the NetGroup constructor. 
    // The GroupSpecifier determines the properties of the group 
    var groupSpecifier:GroupSpecifier; 
    groupSpecifier = new GroupSpecifier("com.aslrexample/" + groupNameText.text); 
    groupSpecifier.postingEnabled = true; 
    groupSpecifier.serverChannelEnabled = true; 
    netGroup = new NetGroup(netConnection, groupSpecifier.groupspecWithAuthorizations()); 
    netGroup.addEventListener(NetStatusEvent.NET_STATUS, NetStatusHandler); 
    StatusMessage("Join \"" + groupSpecifier.groupspecWithAuthorizations() + "\"\n"); 
} 
// Called when you the chatText field has focus and you press Enter. 
private function DoPost(e:ComponentEvent):void{ 
    if(joinedGroup){ 
    // Build the message to post. 
        var message:Object = new Object; 
        message.user = userNameText.text; 
        message.text = chatText.text; 
        message.sequence = sequenceNumber++; 
        message.sender = netConnection.nearID; 
    // Post the message to the group. 
        netGroup.post(message); 
        StatusMessage("==> " + chatText.text + "\n") 
    } else { 
        StatusMessage("Click Connect before sending a chat message"); 
    } 
    ClearChatText(); 
}

A client can send short ActionScript messages directly to a member of a peer-to-peer group without having a direct connection to that member. This feature is called directed routing. Directed routing leverages the full transitive connectivity and the geometric properties of the Group's self-organized structure to route messages through the group.

Use directed routing to send a message to a specific client, or to construct a DHT (distributed hash table).

Successful routing of the message requires the direct participation of all peers along the dynamic path between the sender and intended recipient. Each peer acts as a relay point for the message. Peers do not automatically relay received messages. Use ActionScript to handle the receipt and local processing or forwarding of a message. Message delivery is not guaranteed.

The bandwidth load of message routing is distributed among the members of the group, it is not concentrated at the server.

 Adobe Evangelist Tom Krcha explains directed routing in an article on his blog, Flash Realtime: Directed routing explained.

The following are the Server-Side ActionScript directed routing APIs:

• NetGroup.sendToAllNeighbors()

• NetGroup.sendToNearest()

• NetGroup.sendToNeighbor()

The following are the client-side ActionScript 3.0 directed routing APIs:

• NetGroup.sendToAllNeighbors()

• NetGroup.sendToNearest()

• NetGroup.sendToNeighbor()

Clients can send ActionScript objects through the peer group reliably. This feature is called object replication. Object replication allows all members of an RTMFP group to have a consistent view of a set of objects. Use it to replicate workspaces, create whiteboards, and transfer files, synchronize nodes with a log of operations, and so on.

Object replication uses the full transitive connectivity of the group’s self-organized structure. It replicates objects through the group from nodes that have the objects to nodes that need the objects. Each object is indexed by a number that must be unique across the entire group. The objects must remain immutable.

 For a detailed explanation of object replication, including a sample application, see Adobe Evangelist Tom Krcha’s blog post File Sharing over P2P in Flash Player 10.1 with Object Replication.

Use the following client-side ActionScript 3.0 APIs to replicate an object within a group:

• NetGroup.addHaveObjects()

• NetGroup.addWantObjects()

• NetGroup.denyRequestedObject()

• NetGroup.removeHaveObjects()

• NetGroup.removeWantObjects()

• NetGroup.writeRequestedObject()

Use the following Server-Side ActionScript APIs for object replication and other RTMFP group features:

• ByteArray class

• File.readBytes()

• File.writeBytes()

To complete a tutorial before learning more about the details of multicasting, see Multicast media (RTMFP).

Multicasting is distributing audio and video data among members of a group. The server doesn’t send data to each client—the data is distributed among peers. Multicasting allows few publishers to send a large amount of data. To multicast media, pass a groupspec to the NetStream constructor. Call NetStream.publish() or NetStream.play() to multicast the data. You can use the client-side NetStream class and the server-side NetStream class to multicast data.

Flash Media Server supports both application-level multicast and IP multicast. You can also use application-level multicast and IP multicast cooperatively for a single stream, this use case is called multicast fusion. Multicast fusion combines both broadcast techniques to support higher quality of service. Within a firewall, use IP multicast. Outside the firewall, or on networks that don’t support IP multicast, use application-level multicast. Multicast fusion lets your neighbor outside the firewall receive fragments of video that it cannot receive via IP multicast.

Flash Media Server can multicast streams delivered to it over RTMP connections. For example, Flash Media Live Encoder can deliver a stream to Flash Media Server over RTMP and Flash Media Server can multicast it to groups over RTMFP.

Understand the following about multicast:

• Any number of streams can be published into a group. However, this practice is not recommended because each group member consumes and relays all streams, even if the streams aren’t playing at that specific client.

• Streams of the same name can be published into a group.

  When a client requests to play the stream name, it plays the first stream with that name that it can find. If the publisher for that instance of the named stream stops, the playing client resets to another instance of the named stream and a "NetStream.MulticastStream.Reset" event is dispatched. Within an RTMFP group, there is no single arbiter of stream state that prevents multiple clients from publishing streams with the same name. (In traditional, unicast stream publishing, Flash Media Server is aware of stream state.) This is a significant reason for the improved scalability of multicast streams. However, to protect against stream name collisions or hijacking, define a publish password for the group and providing the groupspec with authorizations to trusted publishers only. Pass a groupspec without authorization to all other clients to prevent them from publishing competing streams under the same name.

• Publishers can call NetStream.send() to inject data into a group.

• When a client is in an RTMFP group in which a live multicast stream is playing, the client may act as a relay point for that stream to some number of direct neighbors. To control this number, use the NetStream.multicastPushNeighborLimit property. The default value is to 4. All the peers within a group work co-operatively to get the stream to each other. Each client is not pulling the stream from the server independently. For this reason, consider the expected average client uplink capacity when selecting the bitrate for the multicast stream you publish. Choosing a bitrate that's too high may result in peers not being able to relay the stream smoothly.

  Note: This requirement is specific to P2P multicast. IP multicast, which can be used simultaneously with P2P multicast, can be used for higher bitrate, live multicast streams in a local area network.

The NetGroup entry in ActionScript 3.0 Reference contains a peer-assisted video and text chat example. The example is a Flex MXML file. To use Flash Pro instead of Flash Builder, see the example for the NetGroup.post() entry which is an AS file.

Adobe Evangelist Tom Krcha has several tutorials and video tutorials on his blog, FlashRealtime.com.