Get SpatialOS

Sites

You are viewing the docs for 9.0, an old version of SpatialOS. 10.4 is the newest →

Entity ACLs

Overview

In SpatialOS version 8, the GSim worker exposes APIs for

  • Delegating Components (States) to kinds of Workers entity.delegateState
  • Choosing what Workers can see the Entity entity.addEngineConstraint

These APIs

  • do not persist across snapshots or GSim boundaries
  • cannot be set at instantiation time, requiring often very simple, one-line behaviours simply to set one of them
  • are impossible for any worker besides the GSim to ever understand them, due to them being expressed as Scala codes

To address these issues, and unlock more issue features, these concepts are being re-articulated in the form of an ACL (Access Control List), in a very similar way to files being access controlled on a conventional Operating System.

Every Entity now can have a persistent ACL, which can be defined when the Entity is created, or modified at runtime. This ACL defines what kinds of worker are able to see, and perform certain actions on the Entity.

Examples

Old: entity.delegateState[Position](PhysicsConstraint)

New: entity.setComponentWriteAcl(Position.componentId, PhysicsContraint.toPredicate)

Old: entity.addEngineConstraint(VisualConstraint)

New: entity.setEntityReadAcl(VisualConstraint.toPredicate)

Note - for all new APIs, the effects will persist across GSim migrations and snapshots.

Current Experimental Implementation

The following new methods have been added to the entity interface on the GSim.

  /**
    * Gets the ACL of the Entity, which defines the kinds of things that a Worker
    * can see and do to this Entity
    */
  def acl: EntityACL

  /**
    * Sets the ACL of the entity, which defines the kinds of things that a Worker
    * can see and do to this Entity.
    * This will persist GSim migrations and snapshots.
    */
  def setAcl(acl: EntityACL): Unit

  /**
    * Sets the kinds of Worker that are able to see this Entity.
    * This will persist GSim migrations and snapshots.
    * @param predicate describes the kinds of worker
    */
  def setEntityReadAcl(predicate: WorkerPredicate): Unit

  /**
    * Removes the ability for any Worker to see this Entity.
    * This will persist GSim migrations and snapshots.
    */
  def clearEntityReadAcl(): Unit

  /**
    * Sets what kinds of worker are allowed to be authoritative on a Component.
    * This will persist GSim migrations and snapshots.
    * @param predicate describes the kinds of worker
    */
  def setComponentWriteAcl(component: ComponentId, predicate: WorkerPredicate): Unit

  /**
    * Removes the ability for any worker to be authoritative on a component.
    * This will persist GSim migrations and snapshots.
    */
  def clearComponentWriteAcl(component: ComponentId): Unit

The EntityRecordTemplate class can now be created with an acl parameter

Interaction with old APIs

You can still use old-style delegations, but if your ACL contains a Component ACL, it will override any delegation set through the old APIs.

Delegating to a specific worker using ACLs

As described in the bridge configuration section, each worker has a unique claim that no other worker has. This claim is the string "engineId:<worker ID>" (the specific worker claim). To delegate a component to a specific worker, you can set the component’s write ACL to be the worker’s specific worker claim.

Further Work

This initial Entity ACL framework lays down the foundations for a number of upcoming features.

  • Being able to decide what kinds of Worker can invoke RPCs on particular Components
  • Being able to decide what kinds of Worker can see particular Components of an Entity
  • Allowing arbitrary Workers to create new Entities
  • Allowing arbitrary Workers to alter Component authority