116 lines
2.4 KiB
Markdown
116 lines
2.4 KiB
Markdown
---
|
|
tags: api/syscall
|
|
references:
|
|
- client/service_registry.ts
|
|
- client/plugos/syscalls/service_registry.ts
|
|
---
|
|
|
|
The Service API exposes a simple service registry leveraged by various parts of SilverBullet. See [[Service]].
|
|
|
|
<!--#lua spacelua.renderApiDocumentation("service") -->
|
|
## service.define
|
|
|
|
`service.define(spec)`
|
|
|
|
Defines a service that can be discovered by selector.
|
|
|
|
**Parameters:**
|
|
|
|
- `spec` (`table`) — Selector, match rule, and run callback.
|
|
|
|
**Example:**
|
|
|
|
```lua
|
|
service.define { selector = "greeter", match = {}, run = function(name) return "Hello " .. name end }
|
|
```
|
|
|
|
## service.discover
|
|
|
|
`service.discover(selector, data)`
|
|
|
|
Discovers matching services sorted by descending priority.
|
|
|
|
**Parameters:**
|
|
|
|
- `selector` (`string`) — Service selector.
|
|
- `data` — Value passed to match callbacks.
|
|
|
|
**Returns:**
|
|
|
|
- `table` — Matching service descriptors.
|
|
|
|
## service.invoke
|
|
|
|
`service.invoke(match, data)`
|
|
|
|
Invokes a previously discovered service match.
|
|
|
|
**Parameters:**
|
|
|
|
- `match` (`table`) — Service match returned by service.discover.
|
|
- `data` — Value passed to the service.
|
|
|
|
**Returns:**
|
|
|
|
- Value — Service result.
|
|
|
|
## service.invokeBestMatch
|
|
|
|
`service.invokeBestMatch(selector, data)`
|
|
|
|
Discovers and invokes the highest-priority matching service.
|
|
|
|
**Parameters:**
|
|
|
|
- `selector` (`string`) — Service selector.
|
|
- `data` — Value used for matching and invocation.
|
|
|
|
**Returns:**
|
|
|
|
- Value — Best matching service result.
|
|
|
|
**Example:**
|
|
|
|
```lua
|
|
local greeting = service.invokeBestMatch("greeter", "Pete")
|
|
```
|
|
<!--/lua-->
|
|
|
|
# Architecture
|
|
|
|
Services are built on top of [[Event|Events]]. 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
|
|
|
|
```space-lua
|
|
service.define {
|
|
selector = "greeter-service",
|
|
match = {},
|
|
run = function(name)
|
|
return "Hello " .. name
|
|
end
|
|
}
|
|
|
|
service.define {
|
|
selector = "greeter-service",
|
|
match = function(name)
|
|
if name == "Pete" then
|
|
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")}
|
|
|