Repo refactor: rename "website" to "docs"

docs/API/service.md

@@ -0,0 +1,62 @@
+#api/syscall
+
+Exposes a simple service registry API leveraged by various parts of SilverBullet, see [[Service]].
+
+# 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",
+  -- 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).