Actor Protocol

Actor Interface

To speak to an actor, we simply send a statement along with the objects that the statement references. If the actor is on the web, we simply send the request with an HTTP POST.

The message sent to the actor is a Hum data frame and looks like this:

---
Data: Action request sent to remote actor.
Action:
. statement: Assemble coffee-drink.
. request: r756446356-33. 
. coffee-drink:
. . recipe: latte.
. . decaffeinated: Yes.
. . skim-milk: No.
---

In the back-plane, the message carries various data that is used by the delivery system. For example: unique message identifier, source address, time sent, digital signature. Because such data serves the back-plane, not the business process, we do not show that data here. That data is in the tranport layer, not the actor interface layer.

Actor Address

The actor's address on the web is a URI that looks like this:
.
http://www.server.com/.../actor/1234
.
where "1234" in the example is the actor's local identifier. The local identifier can be any string. We suggest anything that works well in a URI as a good-enough choice.

If we need privacy or security, the simple solution is to use HTTPS. The protocol is otherwise unchanged.

Registration

The actor registers itself with a Resource Manager by sending a message to a Resource Manager. The message is sent with an HTTP POST. The actor simply tells the manager its address and a list of the roles it can perform. Optionally, the actor can give its "quit time" so that the resource manager will avoid assigning tasks which would exceed the quit time.

The resource manager has a URI that looks like this:
.
http://www.server.com/.../resourceManager/4321
.
where "4321" is the resource manager's local identifier.

The message sent to the resource manager is a Hum data frame and looks like this:

---
Data: Remote actor reporting for work.
Event: 
. statement: Remote actor is available on schedule enclosed.
. Actor:
. . name: One-Arm Charlie.
. . roles: coffee-mixer, donut-fetcher.
. . address: https://www.coffeeshop314159/robot/OneArmCharlie.
. . key: www.coffeeshop314159/robot/OneArmCharlie.
. Schedule:
. . begin: now.
. . end: 2010.12.31 23:59. (Lease expires.)
---

Quit

The actor can quit (de-register) at any time as long as it is not currently working a request. It does that by sending a message to the resource manager. The "quit notice" is sent in a data frame that looks like this:

---
Data: Quit notice.
Event: 
. statement: Actor will be unavailable per reason for period.
. actor: www.coffeeshop314159/robot/OneArmCharlie. 
. reason: Robot going off-line for safety inspection.
. period:
. . start: now.
. . duration: 30 minutes.
---

Completion Report

When an actor completes an request, it sends back a "completion report" in a data frame that looks like this:

---
Data: Work completion report.
Completion-Report.
. statement: Actor consumed resources while completing request.
. actor: www.coffeeshop314159/robot/OneArmCharlie.
. request: r756446356-33.
. resources:
. . coffee-mech: 47 seconds.
. . milk: 500 ml.
. . expresso: 1 shot.
---

Trouble Report

When an actor cannot complete a request, it sends back a "trouble report" in a data frame that looks like this:

---
Data: Actor cannot complete assigned request.
Event:
. statement: Actor encountered problem while working request.
. actor: www.coffeeshop314159/robot/OneArmCharlie.
. request: r756446356-33. (request that cannot be completed)
. problem:
. . category: Missing material.
. . reason: Skim milk container is empty.
. . status: Coffee-mech is waiting for material.
---