plainleaf/docs/API/service.md

tags, references

tags	references
api/syscall	client/service_registry.ts client/plugos/syscalls/service_registry.ts

Exposes a simple service registry API leveraged by various parts of SilverBullet, see Service.

Architecture

Services are built on top of Event. When a service is defined, it registers two event listeners:

1. discover:<<selector>> — for service discovery
2. service:<<guid>> — for invocation

Discovery broadcasts on the event bus and collects all matches, sorted by priority. Invocation calls the specific service's run callback.

Example

service.define {
  selector = "greeter-service",
  -- no priority set
  match = {},
  run = function(name)
    return "Hello " .. name
  end
}

service.define {
  selector = "greeter-service",
  match = function(name)
    if name == "Pete" then
      -- takes precendence with an exact match
      return {priority=10}
    else
      return nil
    end
  end,
  run = function(name)
    return "Hello Pete, so happy to see you!"
  end
}

To invoke: ${service.invokeBestMatch("greeter-service", "Pete")} and ${service.invokeBestMatch("greeter-service", "Hank")}

API

service.define(spec)

Defines a service matching a selector.

Spec arguments:

• selector: service selector, can contain wildcards (e.g. hello:*)
• match(data): callback (data argument), returns a match table if this service is a match or nil otherwise. A match table is service specific, but at least contains a priority key to set the service priority (used for sorting by service.discover and service.invokeBestMatch). Instead of a function can also simply be a match object directly.
• run(data): callback to be invoked when the service is invoked

service.discover(selector, data)

Discovers previously defined service matching a given selector.

Return value is a list of tables (can be empty) with keys:

• id: guid of the service (automatically generated)
• priority: priority of service match (list will already be pre-sorted based on this key if present)

service.invoke(match, data)

Invokes a service match (as returned by #service.discover(selector, options)).

service.invokeBestMatch(selector, data)

Performs a discover based on the selector, then immediately performs and invoke on the best match (based on priority).