Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
23 changes: 22 additions & 1 deletion docs/runtime-host.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ plugin, the plugin calls back into the host.
| `MintScopedStream(request)` | Mint a short-lived stream grant for plugin-owned public access workflows. |
| `CallPluginHTTP(request)` | Invoke another installed plugin's HTTP route through the host control plane. |
| `ReadInstanceState(key)` | Read one key of the calling instance's encrypted, host-scoped state. |
| `WriteInstanceState(key, value)` | Write one key of that state. Key ≤ 256 bytes, value ≤ 256 KiB, ≤ 256 keys per scope. |
| `WriteInstanceState(key, value, expected_version?)` | Write one key of that state. Key ≤ 256 bytes, value ≤ 256 KiB, ≤ 256 keys per scope. With `expected_version`, write only if no one else wrote the key since it was read; see [Shared state](#shared-state). |
| `ReportNetworkAccessStatus(status)` | Push a `network_access_provider.v1` status change so the host does not poll. |

## Using it from a plugin
Expand Down Expand Up @@ -177,6 +177,27 @@ body, decodes the response into `Response`, and returns `*runtimehost.HTTPStatus
for HTTP status codes 400 and above. The lower-level `CallPluginHTTP` remains
available when a plugin needs custom content types or raw bytes.

### Shared state

Every API server runs its own process of a plugin, and all of them read and
write the same instance state on the API host. Two processes that read a
key, change it, and write it back can lose one of the changes. Use
`UpdateInstanceState` for such a key: it writes only if the key is unchanged
since the read, and otherwise reads again and repeats your change.

```go
err := host.UpdateInstanceState(ctx, "profiles", func(current []byte, found bool) ([]byte, error) {
settings := decode(current, found)
settings[profileID] = updated
return encode(settings)
})
```

The function can run more than once, so it must not have side effects.
`ReadInstanceStateVersion` and `WriteInstanceStateIf` are the two steps on
their own. A host that doesn't keep versions answers
`ErrInstanceStateUnversioned`; `UpdateInstanceState` then writes nothing.

### Addressing events

`PublishEvent` broadcasts to every matching `event_consumer.v1` subscription.
Expand Down
67 changes: 58 additions & 9 deletions pkg/pluginproto/silo/plugin/v1/runtime_host.pb.go

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

4 changes: 4 additions & 0 deletions pkg/pluginsdk/runtimehost/client.go
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ import (
"context"
"fmt"
"net/http"
"sync/atomic"
"time"

"google.golang.org/grpc"
Expand All @@ -17,6 +18,9 @@ import (

type Client struct {
rpc pluginv1.RuntimeHostClient
// stateVersions caches whether the host keeps instance state versions:
// 0 not known yet, 1 yes, 2 no.
stateVersions atomic.Int32
}

type CallPluginHTTPRequest struct {
Expand Down
164 changes: 164 additions & 0 deletions pkg/pluginsdk/runtimehost/instance_state_version.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,164 @@
package runtimehost

import (
"context"
"errors"
"fmt"
"math/rand/v2"
"time"

"google.golang.org/grpc/codes"
"google.golang.org/grpc/status"

pluginv1 "github.com/Silo-Server/silo-plugin-sdk/pkg/pluginproto/silo/plugin/v1"
)

// ErrInstanceStateConflict means another write changed the key after the
// version the caller expected. Read the key again and redo the change.
var ErrInstanceStateConflict = errors.New("runtimehost: instance state key changed since it was read")

// ErrInstanceStateUnversioned means the host doesn't keep versions, so it
// can't make a write conditional.
var ErrInstanceStateUnversioned = errors.New("runtimehost: host does not keep instance state versions")

// maxUpdateAttempts bounds UpdateInstanceState's retries on conflict.
const maxUpdateAttempts = 8

// Conflict backoff: full jitter over a window that doubles from
// conflictBackoffBase up to conflictBackoffMax, so writers that collided
// spread out instead of colliding again.
const (
conflictBackoffBase = 10 * time.Millisecond
conflictBackoffMax = 500 * time.Millisecond
)

// conflictBackoff is the wait before attempt n+1 after n conflicts (n >= 1).
func conflictBackoff(n int) time.Duration {
window := conflictBackoffBase << (n - 1)
if window <= 0 || window > conflictBackoffMax {
window = conflictBackoffMax
}
return rand.N(window) + 1
}

// VersionedState is one key's value and the version it was read at. Version
// is 0 when Found is false.
type VersionedState struct {
Value []byte
Found bool
Version int64
}

// ReadInstanceStateVersion reads a key with its version. It returns
// ErrInstanceStateUnversioned on a host that doesn't keep versions.
func (c *Client) ReadInstanceStateVersion(ctx context.Context, key string) (VersionedState, error) {
if err := validateInstanceStateKey(key); err != nil {
return VersionedState{}, err
}
resp, err := c.rpc.ReadInstanceState(ctx, &pluginv1.ReadInstanceStateRequest{Key: key})
if err != nil {
return VersionedState{}, err
}
c.recordStateVersions(resp.GetVersioned())
if !resp.GetVersioned() {
return VersionedState{}, ErrInstanceStateUnversioned
}
if !resp.GetFound() {
return VersionedState{}, nil
}
return VersionedState{Value: append([]byte(nil), resp.GetValue()...), Found: true, Version: resp.GetVersion()}, nil
}

// WriteInstanceStateIf writes value only if the key is still at
// expectedVersion (0: the key must not exist), and returns the new version.
// It returns ErrInstanceStateConflict when another write got there first,
// and ErrInstanceStateUnversioned, without writing, on a host that doesn't
// keep versions: such a host would ignore the condition. The first call on
// a client reads the key once to find out, unless a read already did.
func (c *Client) WriteInstanceStateIf(ctx context.Context, key string, value []byte, expectedVersion int64) (int64, error) {
if err := validateInstanceStateKey(key); err != nil {
return 0, err
}
if len(value) > MaxInstanceStateValueBytes {
return 0, fmt.Errorf("runtimehost: instance state value for %q is %d bytes, limit %d", key, len(value), MaxInstanceStateValueBytes)
}
versioned, err := c.hostKeepsStateVersions(ctx, key)
if err != nil {
return 0, err
}
if !versioned {
return 0, ErrInstanceStateUnversioned
}
resp, err := c.rpc.WriteInstanceState(ctx, &pluginv1.WriteInstanceStateRequest{Key: key, Value: value, ExpectedVersion: &expectedVersion})
if status.Code(err) == codes.Aborted {
return 0, ErrInstanceStateConflict
}
if err != nil {
return 0, err
}
if resp.GetVersion() == 0 {
return 0, ErrInstanceStateUnversioned
}
return resp.GetVersion(), nil
}

// hostKeepsStateVersions reports whether the host honors expected_version,
// reading key to find out the first time.
func (c *Client) hostKeepsStateVersions(ctx context.Context, key string) (bool, error) {
switch c.stateVersions.Load() {
case 1:
return true, nil
case 2:
return false, nil
}
resp, err := c.rpc.ReadInstanceState(ctx, &pluginv1.ReadInstanceStateRequest{Key: key})
if err != nil {
return false, err
}
c.recordStateVersions(resp.GetVersioned())
return resp.GetVersioned(), nil
}

func (c *Client) recordStateVersions(versioned bool) {
if versioned {
c.stateVersions.Store(1)
} else {
c.stateVersions.Store(2)
}
}

// UpdateInstanceState reads key, passes its value to update, and writes what
// update returns only if no other write changed the key in between. On a
// conflict it waits a short, random, growing time, then reads again and
// calls update again, a few times at most, so
// update must be safe to repeat and should not have side effects. An error
// from update stops the loop and is returned as is.
//
// Use it when several API servers can change the same key, such as one
// record shared by every process of the plugin.
func (c *Client) UpdateInstanceState(ctx context.Context, key string, update func(current []byte, found bool) ([]byte, error)) error {
for attempt := range maxUpdateAttempts {
if attempt > 0 {
timer := time.NewTimer(conflictBackoff(attempt))
select {
case <-ctx.Done():
timer.Stop()
return ctx.Err()
case <-timer.C:
}
}
current, err := c.ReadInstanceStateVersion(ctx, key)
if err != nil {
return err
}
next, err := update(current.Value, current.Found)
if err != nil {
return err
}
_, err = c.WriteInstanceStateIf(ctx, key, next, current.Version)
if !errors.Is(err, ErrInstanceStateConflict) {
return err
}
}
return fmt.Errorf("%w: gave up on %q after %d attempts", ErrInstanceStateConflict, key, maxUpdateAttempts)
}
Loading
Loading