Define the countertop API

[slifty]

Task

Description

We have an issue already for creating the countertop (#23) and two issues that talk about the need for an API to communicate with the countertop (#65 and #66).

This issue is a blend of a discussion issue and a task; I would like to use it to define the initial developer API for the countertop. This is the API that developers will use to do things like:

• Register, configure, and activate appliances.
• Subscribe to data events.
• Start and stop the countertop / processing pipeline.

Relevant Resources / Research

None

Related Issues

• 23

• 65

• 66

• 30

[slifty]

Note: for the purposes of this phase I think we should not design around Docker. I would like to consider creating some Docker / Appliance utilities, including a root Docker image that all appliances buld from in their docker files, and a parallel DockerAppliance which would serve as a shim to interact with that docker image. This way our appliance ecosystem would support Docker, but would not prescribe it.

We talked a fair amount in #65 about the desire to not have appliances be dependencies of this repository, and moving to having instance repositories of TV kitchen that define an individual countertop topology. This means that the countertop API will not load appliance packages directly since it won't have access to the modules directly.

With that model I immediately see two ways an appliance could be registered in the countertop:

1. Registering Appliance prototypes with the countertop, thus allowing the countertop to create instances as it needs. Instances would then be requested via API (with configurations). The countertop would manage creating the appliance instances.

2. Registering instantiated / configured appliances could be passed to the countertop directly.

In theory both of these paths could work.

The benefits of registering instances

1. It feels intuitive -- the user has complete control over the configuration and setup of the appliance and they register something directly.

2. The countertop does not need to expose configuration options (which means that it does not need to be updated if the IAppliance configuration API changes).

The benefits of registering prototypes

1. The countertop has complete control over how and when appliances are instantiated. For example, we talked about creating one appliance per stream / data pair -- this would mean that an individual appliance prototype / configuration pair might be instantiated multiple times in a given topology.

Note: I think we would need to create a clone method in IAppliance to support this otherwise.

2. Implementation scripts would not need to know how to create and configure appliances; rather, they would just need to know how to interact with the countertop API. For example, this would mean the countertop would be the only thing that needs to know how to handle instantiation errors from appliances.

3. Treating prototype registration as a separate step, would decouple the act of creating appliances from registering them. For instance maybe someone would want to create an implementation tool where the types of appliances that are possible in a topology are defined by a config file, but the definition of the topology itself is defined via a user interface, API, or command line tool.

---

Right now I am leaning towards the more flexible (but potentially more verbose) architecture of registering prototypes as a first step.

[slifty]

All right, how about this:

• registerAppliance( prototype, configuration ) :: adds an appliance to the countertop, returns an ID. If the countertop has started already it will start the appliance immediately. If the countertop has not been started, the appliance will not be started. Multiple copies of a given appliance may be created to process multiple data streams.

• deregisterAppliance( applianceID ) :: removes a given appliance from the countertop.

• getAppliances() :: returns a list of appliance prototype / configuration pairs.

• getWorkers() :: returns a list of active countertop workers (there is one worker per appliance + source pair).

• start() :: starts the countertop (and all appliances registered).

• stop() :: stops the countertop (and all appliances registered).

• on() :: register event listeners (list of events TBD; possibly just the appliance events we already have).

This still allows us to create appliances on demand without relying on half baked non-features such as cloning, but feels a bit more intuitive because adding an appliance does not become a two step process.

---

EDIT: I had originally suggested addAppliance / removeAppliance, but I think maybe register / deregister might be better since add might imply instances.