Implementation WIP

Collections are under heavy development and major parts of the API will change as features are added.

What are Wrangler Collections?

Wrangler Collections are a Wrangler provided wrapper around subscriptions that allows a pico to maintain a "collection" of other picos, by using subscription relationships. The owner of the collection accepts subscription requests with a set Tx_role and Rx_role that match the collection parameters. The developer is then able to access the collection members by calling a function from the io.picolabs.collection ruleset.

The following is an example of a collection. The CollectionPico maintains subscriptions with collection members. It can also have subscriptions with picos that are not part of the collection.

Querying the members() function of collections returns the relevant subscription information about each member in the collection:

members() Return Value

/*
[
  {
    "Rx_role": "collection",
    "Tx_role": "member",
    "Tx_host": "http://10.37.94.198:8080",
    "Id": "cjy922iak0032r4bz8je38al5",
    "Tx": "BSQTCB3zp1oaRXXeanJhj8",
    "Rx": "FweGnhgVrmYicWog8pfJ1c",
    "Tx_verify_key": "6gy2Rn2YKCwzntsW6GVjKE1Yxbi3c6QT6PY3yhqDYqAk",
    "Tx_public_key": "4J8agPM9z7Ue31mUsxaBWsVT9pDpdjKQJCEoUDmjCJCk"
  },
  {
    "Rx_role": "collection",
    "Tx_role": "member",
    "Tx_host": "http://10.37.94.198:8080",
    "Id": "cjy922o6p003br4bz82qrhvna",
    "Tx": "CM6gsePpn9Ab1SCkRgi8AY",
    "Rx": "BfhDCpb8hTaULihx2FAJUM",
    "Tx_verify_key": "7Bgn4x5FD8vExdBdvPvXmVGPNRzCz3XMp1CLzzNQEDyt",
    "Tx_public_key": "5eAo9Lgx8jccGxGvmF7P5GgCYZJyTy99iHMtNGMhXdxA"
  },
  {
    "Rx_role": "collection",
    "Tx_role": "member",
    "Tx_host": "http://10.37.94.198:8080",
    "Id": "cjy922sa1003ir4bzeafr390e",
    "Tx": "NRKkM5QT12HewbsxQYCgXY",
    "Rx": "QtshCUNrZa1bP19MErnjW",
    "Tx_verify_key": "Cg7HcTmoZjPaBEn1ueHHfiL6zB69T4Xa2sLRUT7WGNn5",
    "Tx_public_key": "HFRf82ZBVg9fDouMhY15XoJ3BVXmNi1BnhzNtvkGJFDr"
  }
]
*/

Creating a Collection

A collection can be created by installing the io.picolabs.collection ruleset in the desired collection manager and then sending subscription requests with the required Tx_role and Rx_roles. The default Tx_role and Rx_role is "collection" and "member" respectively, but these can (and should) be set to something else to prevent collisions.

Given a Collection Pico's WellKnown add self to Collection

rule addSelfToCollection {
  select when example addToCollection
  pre {
    collectionLoc = event:attr("collectionManager")
  }
  always {
    raise wrangler event "subscription" attributes {
      "wellKnown_Tx": collectionLoc,
      "Rx_role":"member",
      "Tx_role":"collection"
    }
  }
}

When the subscription is created and the pico is added to the collection the collection pico will raise event wrangler:new_member that can be selected on.

Send a Welcome Message to New Collection Members

rule onNewCollectionMember {
  select when collection new_member
  pre {
    subInfo = event:attr("bus") // Same attributes as given to wrangler subscription_added
  }
  event:send({"eci":subInfo{"Tx"}, "domain":"example","type":"welcome_to_collection"})
}

Sending Messages to Collection Members

Messages can be sent to collection members by using the return value of the members() function to loop through members with a foreach and send an event to each Tx.

They can also be sent by raising the wrangler:send_event_to_collection_members API event. It internally uses the Rx_role of the collection pico in the subscription so be wary of collisions.

Send an Event to All Collection Members

rule sendEventToNodes {
  select when test test
  always {
    raise wrangler event "send_event_to_collection_members" attributes {
      "domain":"wrangler",
      "type":"child_creation",
      "attrs":{
        "name":"CreatedBySubscription"
      }
    }
  }
}