Skip to content

feat(runtimehost): make instance state writes conditional - #60

Merged
Quick104 merged 3 commits into
mainfrom
feat/instance-state-versions
Nov 18, 2026
Merged

Quick104 merged 3 commits into
mainfrom
feat/instance-state-versions

Conversation

@Quick104

@Quick104 Quick104 commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Problem

Every API server runs its own process of a plugin against one shared instance state, so two
read-modify-write cycles on the same key can lose an update. Plugins work around it with sharded
keys and hand-written leases.

Approach

A read returns the key's version, and versioned tells the plugin the host keeps versions. A
write may set expected_version (0: the key must not exist); the host refuses it with ABORTED when
the key changed. The client adds ReadInstanceStateVersion, WriteInstanceStateIf and
UpdateInstanceState, which reads, applies the change, and retries after a conflict, up to 8
attempts. Between attempts it waits a random time in a window that doubles from 10 ms to 500 ms, so
servers that collided don't collide again at once, and it stops when the context ends.

On a host without versions these return ErrInstanceStateUnversioned and write nothing.
WriteInstanceStateIf learns whether the host keeps versions before its first conditional write,
so it never sends one to a host that would apply it unconditionally.

Compatibility and release

Additive proto fields. An unset expected_version keeps today's unconditional write.

Related changes

Validation

  • go test ./..., go vet ./... and every example build: pass.
  • gofmt -l . lists only pkg/pluginsdk/runtime/scan_source_test.go, which is unformatted on main
    and not touched here.
  • Regenerating the protobuf code with the repo's buf leaves it unchanged. make proto itself stops
    at its protoc check on this machine, though generation doesn't use protoc.
  • On shared dev, a plugin's UpdateInstanceState raised the version on each write; a write at a
    stale version and a create-only write of an existing key were both refused as conflicts.

Evidence

Evidence: https://evidence.siloserver.org/r/silo-plugin-sdk/pr-60/

AI Disclosure

  • Harness: Claude Code, run from T3 Code
  • Tool(s): Claude Code (implementation); Codex CLI (independent review)
  • Model(s): claude-opus-5-5 (implementation); gpt-6.1-sol (review)
  • Involvement: Fully AI-generated, human verified
  • Adversarial review: the same Codex (gpt-6.1-sol) review. It found that WriteInstanceStateIf wrote
    first and checked for version support afterwards, so an older host overwrote the value; it now
    checks first.
  • Later review (2026-11-18): Claude Code (claude-fable-5-2) rebased this onto main and applied the fixes; claude-opus-5-5 and gpt-6.2-sol (Codex) each reviewed it independently. No findings on this change.

🤖 Generated with Claude Code

Note

Add versioned, conditional instance-state writes to runtimehost.Client

  • Adds ReadInstanceStateVersion, WriteInstanceStateIf, and UpdateInstanceState in instance_state_version.go. UpdateInstanceState rereads and reruns its callback after a conflict, up to 8 attempts with full-jitter exponential backoff.
  • Extends the runtime-host protobuf schema in runtime_host.proto with version/versioned read fields, optional expected_version on writes, and a version in the write response. Regenerated bindings in runtime_host.pb.go.
  • The client caches host version-support in an atomic tri-state flag and returns a distinct ErrUnversionedHost error when the host lacks version support. Conflicting gRPC Aborted responses map to a package conflict error.
  • Documents shared instance state and the update pattern in runtime-host.md, including that the UpdateInstanceState callback may run repeatedly and must not have side effects.
  • Risk: hosts that do not implement the new version/expected_version fields get ErrUnversionedHost from WriteInstanceStateIf and UpdateInstanceState; existing unconditional WriteInstanceState behavior is unchanged.

Macroscope summarized 03b2f1a.

@coderabbitai

coderabbitai Bot commented Nov 5, 2026 •

Copy link
Copy Markdown

Warning

Review limit reached

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

  • Ask an admin to enable usage-based reviews

Open in CodeRabbit

Reviews can continue after your included limit without a manual trigger. An admin must approve usage-based billing.

Next included review available in 59 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available. Your 82 included PR review attempts over the past 7 days set your current allowance at 1 review per hour.

Learn how review limits work.

Review configuration:

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 8ce0ca48-c0a3-4376-b1ce-5a04d4419b0d
Commits

Reviewing files that changed from the base of the PR and between 5717267 and 03b2f1a.

Files ignored due to path filters: 1

  • pkg/pluginproto/silo/plugin/v1/runtime_host.pb.go is excluded by !**/*.pb.go
Files selected for processing: 5

  • docs/runtime-host.md
  • pkg/pluginsdk/runtimehost/client.go
  • pkg/pluginsdk/runtimehost/instance_state_version.go
  • pkg/pluginsdk/runtimehost/instance_state_version_test.go
  • proto/silo/plugin/v1/runtime_host.proto
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

@silo-triage silo-triage Bot added the size/L 200–499 added + deleted lines (all files); change volume, not priority. label Nov 5, 2026
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 5, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-18T15:58:46.847689Z 03b2f1a New commits
🔒 Security Review ✅ Completed 2026-11-18T16:01:47.812426Z 03b2f1a New commits
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@silo-kody

silo-kody Bot commented Nov 5, 2026 •

Copy link
Copy Markdown

Silo Kody — review complete

Review finished. Check the inline comments for findings and verify each suggestion against the code and tests.

Reviewing changes in Silo
  • Include the related issue, expected behavior, and validation steps in the PR description.
  • For API changes, describe the effect on Apple and Android clients and Jellyfin compatibility.
  • For plugin changes, identify the affected SDK contract, plugin, and catalog entry.
  • Follow this repository's AGENTS.md and CONTRIBUTING.md.
  • Request another review with @kody start-review in a PR comment.
  • React with 👍 or 👎 to give feedback on individual suggestions.
Review settings
Review Options

The following review options are enabled or disabled:

Options Enabled
Bug ✅
Performance ✅
Security ✅
Business Logic ❌

@silo-kody

silo-kody Bot commented Nov 6, 2026 •

Copy link
Copy Markdown

Silo Kody — review complete

Review finished. Check the inline comments for findings and verify each suggestion against the code and tests.

Reviewing changes in Silo
  • Include the related issue, expected behavior, and validation steps in the PR description.
  • For API changes, describe the effect on Apple and Android clients and Jellyfin compatibility.
  • For plugin changes, identify the affected SDK contract, plugin, and catalog entry.
  • Follow this repository's AGENTS.md and CONTRIBUTING.md.
  • Request another review with @kody start-review in a PR comment.
  • React with 👍 or 👎 to give feedback on individual suggestions.
Review settings
Review Options

The following review options are enabled or disabled:

Options Enabled
Bug ✅
Performance ✅
Security ✅
Business Logic ❌

Quick104 and others added 3 commits November 18, 2026 15:55
Every API server runs its own process of a plugin against one shared
instance state, so two read-modify-write cycles can lose a change. Hosts
now return a version with each read and honor expected_version on a
write, failing with ABORTED when the key changed.

The client adds ReadInstanceStateVersion, WriteInstanceStateIf and
UpdateInstanceState, which repeats the change after a conflict. On a host
that doesn't keep versions they return ErrInstanceStateUnversioned, and
UpdateInstanceState writes nothing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…es it

WriteInstanceStateIf sent the write first and only then noticed the host
keeps no versions, so on an older host it overwrote the value
unconditionally. It now learns whether the host keeps versions before
the first conditional write, from a read it makes once per client or one
the plugin already made, and writes nothing on such a host.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
UpdateInstanceState retried a conflicting write at once, so servers that
collided on a key tended to collide again. It now waits a random time in a
window that doubles from 10 ms to 500 ms between attempts, and stops when
the context ends.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Quick104
Quick104 force-pushed the feat/instance-state-versions branch from 5fddad7 to 03b2f1a Compare November 18, 2026 15:57
@Quick104
Quick104 merged commit 92f17cb into main Nov 18, 2026
4 checks passed
@Quick104
Quick104 deleted the feat/instance-state-versions branch November 18, 2026 18:42
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request go Pull requests that update go code size/L 200–499 added + deleted lines (all files); change volume, not priority. triaged High-confidence review completed; does not mean fixed, validated, or accepted for release.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant