Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
1680c5b
feat(notification-channel): let plugins provide notification destinat…
Quick104 Nov 4, 2026
0051cca
docs(notification-channel): give the host's real retry window
Quick104 Nov 4, 2026
3308195
fix(hello-notification-channel): require an absolute server URL and k…
Quick104 Nov 5, 2026
7ab31d9
feat(notification-channel): restrict destination forms to flat scalar…
Quick104 Nov 6, 2026
6b76b70
fix(hello-notification-channel): keep proxy answers and redirects fro…
Quick104 Nov 18, 2026
fb1f85f
fix(manifest): refuse destination schemas the host can't render or store
Quick104 Nov 18, 2026
71b31aa
docs(notification-channel): match the host's reasons, errors, disabli…
Quick104 Nov 18, 2026
e4ff510
fix(manifest): restrict destination forms to one flat list of plain c…
Quick104 Nov 18, 2026
f88c15a
docs(notification-channel): state the host's retry_after cap and list…
Quick104 Nov 18, 2026
728069f
docs(notification-channel): document the destination form, lifecycle …
Quick104 Nov 18, 2026
7c5836c
docs(notification-channel): separate a returned error from a transpor…
Quick104 Nov 18, 2026
f901f2b
fix(manifest): refuse destination forms a host can't save or render
Quick104 Nov 19, 2026
226a472
docs(notification-channel): state the form rules, RE2 patterns and tr…
Quick104 Nov 19, 2026
9f99756
docs(notification-channel): say when a message's url and image_url ar…
Quick104 Nov 19, 2026
30bce3b
fix(manifest): refuse integer settings a double can't hold and bounds…
Quick104 Nov 19, 2026
d984873
docs(notification-channel): state the retry row as ten attempts over …
Quick104 Nov 19, 2026
c9b77b8
fix(manifest): refuse a secret destination field on a select control
Quick104 Nov 19, 2026
23b6693
fix(manifest): refuse integer bounds beyond what a setting can carry
Quick104 Nov 19, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@ go build ./examples/hello-scheduled-task
go build ./examples/hello-runtime-host
go build ./examples/hello-network-access
go build ./examples/hello-scan-source
go build ./examples/hello-notification-channel
gofmt -l .
```

Expand Down
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ The SDK ships protobuf contracts for every capability the host understands:
- `scan_source.v1`
- `watch_sync_provider.v1`
- `network_access_provider.v1`
- `notification_channel.v1` (see [docs/notification-channel.md](docs/notification-channel.md))
- `audiobook_backend.v1`
- `ebook_backend.v1`

Expand Down
10 changes: 10 additions & 0 deletions docs/compatibility.md
Original file line number Diff line number Diff line change
Expand Up @@ -262,6 +262,16 @@ and ignores the field, so it applies its usual idle-stop rule. The field takes
effect only on a host that both stops idle plugins and reads it; on a host that
never stops idle plugins, it changes nothing.

### New capability types

Manifest validation refuses a capability type its SDK doesn't know, and it
refuses the whole plugin, not only that capability: an older host fails to
install or load it with `plugin capability "<id>": unknown type "<type>"`.
A plugin that declares a newer type, such as `notification_channel.v1`,
therefore needs a host built on an SDK that knows it. Ship a new capability
type in its own plugin rather than adding it to one that must keep working
on older hosts.

### Watch-sync batch size

`WatchSyncProviderDescriptor.max_batch_size` accepts 1 to 1000 from v0.27.0;
Expand Down
272 changes: 272 additions & 0 deletions docs/notification-channel.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,272 @@
# Notification channels

A `notification_channel.v1` capability adds a kind of notification
destination to Silo, such as a push service or a chat app. Users add a
destination of that kind in their notification settings, next to webhooks and
email, and Silo sends it the notifications the profile receives: new
episodes, request updates, and titles from the profile's watchlist that
arrive in the library.

The plugin does two things: it checks a destination's settings, and it sends
one message. Silo does the rest:

- which notifications a profile gets, and each destination's two switches:
`notify_next_up` (new episodes, type `episode.available`) and
`notify_requests` (request updates, `request.*`, and watchlist arrivals,
`watchlist.available`)
- a limit of 30 new-episode and watchlist messages a minute per profile
(request updates aren't limited). Each API server counts on its own, so a
cluster of several servers can send a profile more.
- a durable delivery queue, so a notification survives restarts and a server
going away mid-send
- retries with backoff, and dropping a message after the last retry
- failure counts, shown to the destination's owner, and disabling a
destination whose settings stopped working (see the outcomes below)
- test messages from the settings page
- storing each destination's settings encrypted, and never returning secret
fields through the API

Compare an `event_consumer.v1` plugin subscribed to `notification.created`,
which has to rebuild preferences, retries and deduplication itself.

## Manifest

```json
{
"type": "notification_channel.v1",
"id": "ntfy",
"display_name": "ntfy",
"notification_channel": {
"display_name": "ntfy",
"description": "Push notifications to an ntfy topic.",
"destination_schema": {
"key": "destination",
"json_schema": "{\"type\":\"object\",\"properties\":{\"topic\":{\"type\":\"string\"},\"access_token\":{\"type\":\"string\"}},\"required\":[\"topic\"]}",
"admin_form": {
"fields": [
{ "key": "topic", "label": "Topic", "control": "ADMIN_FORM_CONTROL_TEXT", "required": true },
{ "key": "access_token", "label": "Access token", "control": "ADMIN_FORM_CONTROL_PASSWORD", "secret": true }
]
}
}
}
}
```

- The capability `id` is a lowercase slug. It's stored with each destination,
so keep it stable across releases.
- `destination_schema` is a `ConfigSchema` with a flat form: one object of
string, integer, number or boolean fields, each with optional `title`,
`description`, `default` and `enum`, `minimum`/`maximum` on integer and
number fields, and `format` and `minLength`/`maxLength`/`pattern` on string
fields, plus a top-level `required` list. `additionalProperties` may only
be `false` or absent. `$schema`, `$ref`, `allOf`/`anyOf`/`oneOf`/`not`,
conditionals, nested objects and arrays are refused, because people who
aren't administrators fill the form in on every client. Silo compiles the
schema as JSON Schema draft 2020-12, the draft it uses for all plugin
configuration.
- `admin_form` is required and is one flat list of at least one field: one
form field per schema field, and every form field names a schema field.
Clients render only the form. See [Destination form](#destination-form).
`manifest.ValidateDestinationSchema` checks all of this.
- Silo checks each submitted setting against the schema before calling the
plugin: only declared fields; the value has the declared type; `required`
fields present when a destination is created (a stored secret left blank
on an edit counts as present); `enum`; `minLength`, `maxLength` and
`pattern` on strings; `minimum` and `maximum` on numbers. It doesn't check
`format` (in draft 2020-12 it's only an annotation) or anything else, so
check whatever else matters in `ValidateDestination`.
- `pattern` is Go RE2 syntax (Go's `regexp`: no lookahead, lookbehind or
backreferences), and install refuses a pattern that doesn't compile.
Clients may use it to check input as the user types; the host's check on
save is the one that counts.
- Mark credentials `secret`: the host never returns them, and on an edit the
user leaves them blank to keep the stored value.
- A manifest can declare several `notification_channel.v1` capabilities. One
server answers for all of them; each request carries its `capability_id`.

## Destination form

A destination form is one flat list of fields. Every Silo client has to
render it for people who aren't administrators, so it allows only what a
flat list of scalar fields needs.

| Control | Schema field type |
|---|---|
| `ADMIN_FORM_CONTROL_TEXT` | `string` |
| `ADMIN_FORM_CONTROL_PASSWORD` | `string` |
| `ADMIN_FORM_CONTROL_NUMBER` | `integer` or `number` |
| `ADMIN_FORM_CONTROL_SWITCH` | `boolean` |
| `ADMIN_FORM_CONTROL_SELECT`, with static `options` | `string`, `integer` or `number` |

A field must set `key`, `label` and `control`, and may set `description`,
`placeholder`, `required`, `secret` (string fields only), `default_value`
and, on a `SELECT` only, `options`.

Every form must also be one a client can render and Silo can save, so
install refuses a form unless:

- each field's `key` is exactly its schema property's name: a letter
followed by up to 63 letters, digits, underscores or hyphens, used once
- a field's `required` matches whether the schema's `required` list names
it
- the schema compiles as Silo compiles it, and each `pattern` is valid Go
RE2
- `minimum` is at most `maximum`, `minLength` is at most `maxLength`, and
lengths aren't negative; an integer field's bounds hold at least one whole
number
- an integer value (an option, a default, or what a user enters) is at most
9007199254740991 in either direction, because settings travel as JSON and
protobuf numbers. Use a string field for a larger identifier, such as a
chat ID
- a `secret` field uses the `PASSWORD` or `TEXT` control
- every option value parses as the field's type (an integer field's options
are integers), and no two options have the same value
- a field with `enum` uses a `SELECT`, and its options are exactly the
`enum` values. Every option passes the field's other checks. Without
`enum`, Silo accepts any value of the field's type that passes its
checks, not only the options; declare `enum` to hold it to them.
- a `default` in the schema and a `default_value` on the form are each a
value of the field's type that passes the field's checks and, on a
`SELECT`, is one of the options

Refused:

- `sections` (the generic form doesn't need them: without sections it
renders the fields in order) and `submit_label`
- `show_when`, `dynamic_options` and `exclusive_group_field`. A destination
has no options lookup; the admin `ListConfigOptions` call is for
administrators only.
- `validation`: put `minimum`, `maximum`, `minLength`, `maxLength` and
`pattern` in the JSON schema, where Silo checks them
- `ADMIN_FORM_CONTROL_TEXTAREA`, `multiline`, `rows`,
`ADMIN_FORM_CONTROL_MULTI_SELECT` and an unset control
- a `SELECT` without options, and `options` on any other control

Loosening these rules later is additive; tightening them would break
published plugins, so they start narrow.

## Serving

Register the service with `runtime.WithNotificationChannel`:

```go
sdkruntime.ServeManifestWithOptions(manifestJSON, version, sdkruntime.CapabilityServers{},
sdkruntime.WithNotificationChannel(&channel{}),
)
```

`ServeManifestWithOptions` refuses to start when the manifest declares a
`notification_channel.v1` capability and no server is registered.

### ValidateDestination

Silo calls it before saving a destination. Check the settings and return
`valid: false` with a `message` the user can act on. Return a gRPC error only
when the check itself couldn't run. A network check, such as asking the
service whether a user key exists, is fine. Silo gives the call 10 seconds,
counted once it has reached the plugin; starting a stopped plugin comes
first and isn't part of them. When the plugin doesn't answer in time,
returns a gRPC error, or isn't running, the save fails with `503` (the
plugin isn't available) and `Retry-After: 30`.

A valid answer doesn't mean the settings get saved: Silo checks them first
and saves afterwards, and the save can still fail, for example on the
per-profile destination limit or because another edit landed first. So
`ValidateDestination` must not create remote state, such as a subscription
or a webhook on the service, that would be a problem to leak.

### SendNotification

Silo calls it once per message and destination, possibly from different
servers, and again after a failure. A server claims a send for five minutes;
if that server dies, another one sends it again once the claim runs out, so
a message can arrive twice. `delivery_key` is the same on every attempt:
pass it to the service as an idempotency key where it has one.

The message arrives rendered: `title`, `body`, `url` (opens the item in
Silo; empty when the server has no public URL set) and `image_url` (a
poster, which can expire; empty when there is none). `details` carries the
same fields as the `Notification` type in `pkg/pluginsdk/events` (the
`notification.created` event's payload; identifiers are strings), for
plugins that render their own text. `type` is `episode.available`,
`watchlist.available`, a `request.*` type, or `test` for a test message,
whose `details` are empty. The vocabulary is open.

Map the service's answer onto an outcome:

| Outcome | Use for | Silo then |
|---|---|---|
| `DELIVERED` (or an empty response) | The service accepted the message. | Records the success. |
| `RETRY` | A timeout, a rate limit, a 5xx. Set `retry_after_seconds` when the service says how long to wait. | Tries again later with growing delays. After ten attempts over about a day the message is dropped, and the destination may be disabled (see below). `retry_after_seconds` makes the next wait at least that long, up to a host cap of six hours; it never shortens the schedule. |
| `FAILED` | This message can't be sent, but the destination works. | Drops the message. |
| `DESTINATION_INVALID` | The service definitely refused the settings, such as a revoked token or a deleted topic. | Drops the message and disables the destination at once, until its owner turns it back on. |

`DESTINATION_INVALID` takes effect on the first answer, so return it only when
the service's own response says the settings are wrong. A 401 from a proxy or
CDN, a timeout or a 5xx is `RETRY`.

Because of that cap, a plugin whose service asks for a longer wait, such as
a daily quota that resets in 20 hours, is called again after six hours. It
should then answer `RETRY` again with the wait that remains.

Silo allows 10 seconds to reach the plugin, starting it when needed, and
then 15 seconds for the call. A gRPC error your plugin returns, or no answer
within those 15 seconds, counts as `RETRY`: an ordinary failed attempt,
which retries and can lead to the destination being disabled under the "no
successful send" rule below. Only a failure to reach the plugin counts as
the plugin being unavailable (see below). Put a short reason in `message`;
the destination's owner sees it. Never include secrets.

Silo disables a destination in two cases only:

- the plugin answers `DESTINATION_INVALID`, or
- a message runs out of retries (ten attempts over about a day), or is still
waiting 36 hours after it was queued (for example after several long
`retry_after_seconds` waits), after failed attempts, and the destination
had no successful send and no edit by its owner in the meantime. One
message that keeps failing while others get through doesn't disable it.

A message still waiting after 36 hours is dropped without another send.

A failure to reach the plugin is the plugin being unavailable, not the
destination failing: the plugin is off, removed or not running, the
connection fails or closes (its process exited during the call), or the
call ends with gRPC `Unavailable`. Silo retries such a message like any
other and drops it once it's older than the retry window, but leaves the
destination enabled, so it works again once the plugin is back. Silo also
doesn't disable a destination whose owner saved new settings while the
failing send ran.

A disabled destination is turned off and gets nothing until its owner
turns it back on. Saving new settings clears the reason shown and the
failure count but leaves the destination off.

### What a plugin isn't told

- **Destination changes.** Silo doesn't tell the plugin when a destination
is edited, disabled or deleted. Every call carries the destination's
current settings, so keep no per-destination state that would need
cleaning up.
- **The recipient's language.** Requests carry no locale. Silo renders
`title` and `body`; a plugin that renders its own text from `details`
has no way to pick the recipient's language.

## Compatibility

A Silo server whose SDK predates `notification_channel.v1` refuses to

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

kody code-review Kody Rules high

Compatibility guidance omits the stored metadata reader requirement

Older stored capability metadata readers can fail when newer fields are published. Identify SDK v0.13.1 as the first version that tolerates unknown fields on this path, require older readers to upgrade first, and distinguish decoding from manifest loading without implying that loading retains unknown fields.

Kody rule violation: Scope unknown-field compatibility to the actual Go decoding path and SDK version

Prompt for LLM
File docs/notification-channel.md, line 207:

Compatibility guidance omits the stored metadata reader requirement

Distinguish manifest loading from stored capability metadata decoding in this compatibility guidance. Identify SDK v0.13.1 as the first version tolerant of unknown fields on the stored metadata path, and require older metadata readers to upgrade before newer fields are published. Do not imply that manifest loading retains unknown fields.

Kody rule violation: [Scope unknown\-field compatibility to the actual Go decoding path and SDK version](https://kodus.siloserver.org/settings/code-review/1247142454/kody-rules/3529b3c9-f838-4fa0-91e6-c43a54ca13e3?teamId=ba9922fc-c0ea-4cf8-87bb-9d4f42ffc73e)

Talk to Kody by mentioning @kody

Was this suggestion helpful? React with 👍 or 👎 to help Kody learn from this interaction.

​

​

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

kody code-review Kody Rules high

Compatibility guidance does not cover all manifest compatibility paths

Non-default fields may be serialized, and older hosts may discard fields before comparing manifests, affecting compatibility. Document minimum versions for binary manifest reads, archive installation, startup comparisons, and stored capability decoding, or cover these paths with compatibility tests.

Kody rule violation: Check every compatibility path when adding manifest fields

Prompt for LLM
File docs/notification-channel.md, line 207:

Compatibility guidance does not cover all manifest compatibility paths

Extend the compatibility guidance to identify the minimum supported versions for binary manifest reads, archive installation and startup manifest comparisons, and stored capability decoding. Account for non-default fields being serialized and for older hosts discarding fields before comparing manifests; alternatively, cover these paths with compatibility tests.

Kody rule violation: [Check every compatibility path when adding manifest fields](https://kodus.siloserver.org/settings/code-review/1247142454/kody-rules/2c8adc32-1bd1-41e6-92a0-52a8e9fb9ead?teamId=ba9922fc-c0ea-4cf8-87bb-9d4f42ffc73e)

Talk to Kody by mentioning @kody

Was this suggestion helpful? React with 👍 or 👎 to help Kody learn from this interaction.

​

​

install or load a plugin that declares it: its manifest validation rejects
the whole plugin with `plugin capability "<id>": unknown type
"notification_channel.v1"`. The same happens to a plugin that declares any
capability type the host's SDK doesn't know, so put a notification channel
in its own plugin, not in one that must keep working on older servers.

## Network requests

The host's webhook client refuses private and loopback addresses. A plugin
makes its own requests, so it has to apply the same care: users who aren't
administrators fill in destination settings, so don't let a setting choose
the host a plugin connects to. Fix the service's URL in the plugin, or take
it from the plugin's administrator settings, as
[`examples/hello-notification-channel`](../examples/hello-notification-channel)
does.
28 changes: 28 additions & 0 deletions examples/hello-notification-channel/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
# Hello Notification Channel

A `notification_channel.v1` plugin that sends Silo notifications to an
[ntfy](https://ntfy.sh) topic. It shows:

- declaring a destination kind and its settings form in `manifest.json`
- checking a destination's settings in `ValidateDestination`
- mapping the service's answers onto `SendNotification` outcomes, so the
host retries temporary failures and disables a destination whose token
stops working
- keeping the server URL in the administrator's settings, since users who
aren't administrators fill in destinations

## Build

```sh
go build -o hello-notification-channel ./examples/hello-notification-channel
./hello-notification-channel manifest
```

## Use

Install the binary through **Admin > Plugins**. Optionally set the ntfy
server in the plugin's settings (the default is `https://ntfy.sh`). Each
profile then adds an ntfy destination in its notification settings and
subscribes to the topic in the ntfy app.

See [docs/notification-channel.md](../../docs/notification-channel.md).
Loading
Loading