Skip to content

feat(proto): send each requested season's air date and episode count to request routers - #72

Open
Rhainland wants to merge 4 commits into
Silo-Server:mainfrom
Rhainland:feat/request-season-details
Open

Rhainland wants to merge 4 commits into
Silo-Server:mainfrom
Rhainland:feat/request-season-details

Conversation

@Rhainland

@Rhainland Rhainland commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Problem

Related issue: Silo-Server/silo-server discussion #4454

A season request reaches a request router plugin as TMDB's season numbers and nothing else. Download services number some series differently: TMDB files DAN DA DAN as one 24-episode season, while Sonarr has two seasons of 12. A plugin that matches by number monitors Sonarr's season 1 and gets half of what the user asked for. The plugin has no way to tell which episodes the host meant.

This adds each requested season's first air date and episode count to the request, so a plugin can find the same episodes in its own service by air date.

Approach

RequestDescriptor gets repeated RequestedSeason season_details = 11, one entry per season in seasons, in the same order. RequestedSeason carries the season number, first_air_date (YYYY-MM-DD, empty when TMDB has none yet) and episode_count (0 when unknown). The proto comment describes the matching rule: the season is the first episode_count regular episodes, in airing order, airing on or after first_air_date, or the ones that match when fewer do. A plugin finds each detail by number, since the list can leave seasons out. It matches a season by number when it has no detail, when the detail has no date or a count of 0, when no episode matches, and always for Specials.

The change is additive and first ships in v0.34.0; the branch contains v0.33.0. A host that predates the field, a whole-series request, and a request stored before the host kept the details all send an empty list, and a plugin then matches by number as before. docs/compatibility.md records that presence rule and the README section on season requests describes the field for plugin authors.

The server side (storing the details with each request and sending them) and the Sonarr plugin side are separate pull requests that need this one merged and released first; they link back here.

Validation

  • go test ./..., go vet ./..., the four example builds: pass.
  • make proto: regenerating leaves the committed generated code unchanged.
  • gofmt -l .: only pkg/pluginsdk/runtime/scan_source_test.go, which this change does not touch and which already differs on main.
  • The request router wire test now also checks that season_details arrives, and that a request with only season numbers still delivers them with no details.

Evidence

No user-visible change. The wire test above covers the contract. The server and Sonarr plugin pull requests built on this field were run end to end against a real Sonarr 4.0.20; results are in those pull requests.

Risks

None identified. The field is new and optional; existing plugins ignore it.

Checklist

  • I read and can explain the complete diff.
  • This pull request addresses one concern.
  • Each test this pull request adds meets "Decide what to test".
  • The Evidence section shows how I checked a change nobody sees.

AI Disclosure

  • Harness: Claude Code
  • Tool(s): Claude Code; Codex CLI (review only)
  • Model(s): claude-opus-5-5 (implementation and review); claude-fable-5-2, gpt-6.2-sol, gpt-6.2-astra (review)
  • Involvement: Fully AI-generated, human verified
  • Adversarial review: four independent model reviews (the models above) of the full three-repository change, then of the fixes, on correctness, repository standards and the discussion's request. Findings for this repository: missing compatibility test coverage for the new field and a README gap on seasons without details; both fixed.

Note

Add season_details field to RequestDescriptor for request routers

  • Adds a new RequestedSeason message and a repeated season_details field (number 11) to RequestDescriptor in request_router.proto, carrying season number, first air date, and episode count
  • Documents matching rules for plugins: match regular episodes by air date and count, and fall back to number-based matching when details are missing, unusable, or the season is Specials; details are looked up by season number, not list position
  • Updates generated bindings in request_router.pb.go and the runtime tests to verify populated details and compatibility with requests that omit them
  • Updates README.md and docs/compatibility.md to describe the new field and its behavior with older hosts and plugins
  • Behavioral Change: field is additive and optional; older hosts and whole-series requests send no details, and plugins built before the field ignore it

Macroscope summarized b635842.

A request names seasons by TMDB's numbering. Download services such as
Sonarr split or merge some series differently, so a plugin matching by
number monitors the wrong episodes. RequestDescriptor.season_details
carries each requested season's first air date and episode count, so a
plugin can match the same episodes by air date.
@silo-triage silo-triage Bot added the size/L 200–499 added + deleted lines (all files); change volume, not priority. label Nov 18, 2026
@coderabbitai

coderabbitai Bot commented Nov 18, 2026 •

Copy link
Copy Markdown

Explain Change →

No actionable comments were generated in the recent review.

Walkthrough

RequestDescriptor now includes optional per-season details for season matching. The documentation describes matching and fallback rules. The router test checks that the descriptor carries season details when present and has none when omitted.

Changes: Requested Season Details

Layer / File(s) Summary
Season detail contract and router coverage
proto/silo/plugin/v1/request_router.proto, pkg/pluginsdk/runtime/request_router_test.go, README.md, docs/compatibility.md
RequestDescriptor adds repeated season_details entries with a season number, first air date, and episode count. The router test checks forwarding with and without details. The documentation describes matching by date and episode count, fallback to season number, and compatibility behavior.

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Feature

Suggested reviewers: quick104

Merge Risk: Minimal · up to b6358

This adds optional per-season details to request descriptors so plugins can match seasons across services that number them differently. Existing plugins are unaffected, and the change is low risk to merge. The release tag should match the v0.34.0 date in the compatibility documentation.

Security architecture risk: Minimal · up to b6358

The change adds optional season metadata without adding permissions, credential access, or new request operations. Number-based matching remains the compatibility fallback. No introduced security, ownership, or failure-containment issue was established within this change.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

  • observed — The specifically routed Fulfill method and recordingRequestRouter are test declarations in package runtime_test. Their descriptor channel is created and consumed inside the test; these declarations do not add a production-facing endpoint or shared production state.

Trust Boundaries and Controls

  • inferred — The inspected change enriches data crossing the existing host-to-plugin boundary rather than granting additional authority. Host policy ownership and the supports_seasons restriction remain explicit contract requirements. Enforcement by the external host and downstream plugins is outside the inspected implementation scope.
Pre-merge checks: Passed 4

Check name Status Explanation
Title check Passed The title names the main change: RequestDescriptor now carries each requested season's air date and episode count to request routers, matching the proto field and the stated objective. It is a single …
Description check Passed The description states the problem (TMDB and download-service season numbering differ), the approach (season_details with first air date and episode count, matched by number as fallback), compatibilit…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Title check

Explanation

The title names the main change: RequestDescriptor now carries each requested season's air date and episode count to request routers, matching the proto field and the stated objective. It is a single specific sentence and does not include file lists or vague terms.

Full details: Description check

Explanation

The description states the problem (TMDB and download-service season numbering differ), the approach (season_details with first air date and episode count, matched by number as fallback), compatibility behavior, validation, and risks. It matches the changeset closely.

Finishing Touches

Generate unit tests (beta)

  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Recent review info

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: e0e999dd-942a-4112-9a25-2b3e95abd545
Commits

Reviewing files that changed from the base of the PR and between 9b5b81d and b635842.

Files ignored due to path filters: 1

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

  • README.md
  • docs/compatibility.md
  • pkg/pluginsdk/runtime/request_router_test.go
  • proto/silo/plugin/v1/request_router.proto

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

@silo-kody

silo-kody Bot commented Nov 18, 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 ❌

Comment on lines +52 to +54
// plugin matches by air date rather than by number: the season is the first
// episode_count regular episodes, in airing order, that air on or after
// first_air_date.

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 Bug high

Air-date matching selects regular episodes for Specials requests

A request for season 0 with a date and count can acquire unrelated episodes and omit the requested Specials. Specify a separate matching rule for Specials, such as matching season 0 by number.

Prompt for LLM
File proto/silo/plugin/v1/request_router.proto, lines 52-54:

Air-date matching selects regular episodes for Specials requests

A request for season 0 with a date and count will match regular episodes instead of the requested Specials, so a conforming plugin can acquire unrelated episodes and omit the requested ones. Specify a separate matching rule for Specials, such as matching season 0 by number.

Talk to Kody by mentioning @kody

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

​

​

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Fixed in 90dbbd7: the RequestedSeason comment and docs/compatibility.md now say Specials (season 0) are always matched by number and a host need not describe them. Silo's server never sends season 0 details (it drops season 0 from season requests), and the Sonarr plugin already matches season 0 by number.

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Thanks for clarifying. Matching season 0 by number addresses the issue I raised, and the server and Sonarr behavior you describe is consistent with that rule. I haven’t independently verified commit 90dbbd7.

A Specials season is not regular episodes, so air-date matching would
pick the wrong ones. Say that plugins match season 0 by number.
@silo-kody

silo-kody Bot commented Nov 18, 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 ❌

Brings in v0.33.0 so the release that carries season_details contains it.

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

@Quick104 Quick104 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🤖 Claude Code (claude-opus-5-5)

I merged main into this branch (f6d86d2), so the release that carries season_details also contains v0.33.0. make proto leaves the merged head unchanged, and go vet ./... and go test ./... pass.

Three documentation findings on the contract are below. I'm fixing all three in a commit on this branch, so there's no need to change anything yourself.

Comment thread docs/compatibility.md Resolved
State in the RequestedSeason contract what silo-server and the Sonarr plugin already do: a count of 0, or details that match no episode, fall back to the season number, and a partial match uses the episodes found. Tell plugins to find a detail by number, since the list can leave seasons out, and date the field to v0.34.0, as v0.33.0 shipped without it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@silo-kody

silo-kody Bot commented Nov 18, 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

Copy link
Copy Markdown
Contributor

🤖 Claude Code (claude-opus-5-5)

Review summary

Reviewed head: b635842 (the contributor's commits, a merge of main at v0.33.0, and one documentation fix).

Addressed

Each fix is in b635842. buf generate produced the matching comment change in request_router.pb.go. go vet ./... and go test ./... pass.

Checked and fine

  • Specials: the server never sends season 0 details, and the contract matches season 0 by number. Kody's earlier thread covered this and it was fixed in 90dbbd7.
  • Field 11 on RequestDescriptor is unused on main, and the change is additive.

Left for the maintainers

  • Tag the release that carries this as v0.34.0, or update the version in docs/compatibility.md if it ships under another tag. The server and Sonarr plugin PRs then re-pin to it.

Validation

  • The wire test can't build on the base, because it uses the field this PR adds. It doesn't count as proof that the behavior changed. The SDK only carries the field. The behavior is exercised in the server and Sonarr plugin PRs.
  • Validated features: no passed case shares code with this change. The host doesn't send the field until the server PR lands. Validation tasks: none.
  • User manual: unaffected. siloserver.org doesn't document the request router contract.
  • Apple/Android parity: not applicable.
  • No cross-provider review round ran: the PR adds a proto field and documentation and changes no runtime behavior in this repository.

Verdict

Fit: 8/10 · Readiness: 8/10 — conditional

  • Fit: It fixes a real gap in season requests: series that TMDB and Sonarr number differently, common with anime, fetched the wrong episodes. The field is optional and older plugins ignore it. It holds at 8 because it adds new contract surface.
  • Readiness: The contract is now complete and consistent with the server and the Sonarr plugin. Two conditions remain: the behavior is only shown in those downstream PRs, and the release tag has to match the documented v0.34.0.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request size/L 200–499 added + deleted lines (all files); change volume, not priority.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants