You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
feat(markers): let a marker provider report an incorrect segment - #70
A marker provider can be wrong, and the contract gives the host no way to say so.
TheIntroDB serves an intro range that does not match the file; the only place to
flag it is the service's own website, so the viewer leaves the player, finds the
title and the episode again, and flags it there.
A provider cannot fix this from outside the contract. An http_routes.v1 route
is a browser surface — native clients do not use the plugin-content mounts — and
it is one plugin's own API, so every other marker provider repeats the work and
every client learns each plugin's route and body shape. A route also has no idea
what the host knows, so a client that addresses the wrong item, or the wrong
episode of the right item, sends a flag that settles on the service and cannot be
taken back. The shape for this is under review in Silo-Server/silo-server#3085.
Approach
Reporting becomes part of marker_provider.v1, in three additions:
A separate MarkerReporting service with ReportMarker. Adding an RPC to MarkerProvider would add a method to its released Go server interface and
break providers that implement it directly, which docs/compatibility.md
already rules out. A plugin that does not serve this one answers Unimplemented, and hosts read that as "this provider cannot report".
ReportMarkerRequest carries the same identity a fetch carries, including episode_numbering, plus the segment kind. No bounds: a report is a complaint
that a segment is wrong, not a replacement to store. Its season_number is optional, because on this contract an unset season means "the host could not
place the episode in one" and zero is Specials.
MarkerSegment.reportable, so the provider answers at fetch time whether it
would take a report for that segment now. For a provider that reports through
a shared credential that is "while the operator has configured it" — the
provider decides, so a host never infers this from config entry names.
MarkerReportOutcome keeps reported, already reported, and refused apart.
Already reported is settled, not a failure, which matters because services
commonly key one report per account per item.
The runtime registers the service through a new WithMarkerReporting option, or
on its own when the MarkerProvider server also implements MarkerReportingServer — the same pattern AuthProviderChecks and ConfigurationChecks use. runtime.Client gains a MarkerReporting() accessor.
Compatibility and release impact
Additive. MarkerProvider, CapabilityServers, ServeConfig, and serveManifestOptions keep their shapes: the service reaches the plugin set
through optionalServices, so an unkeyed CapabilityServers literal compiles
exactly as before. The new tests pin both facts, including that MarkerProvider still has its three methods.
Two open vocabularies go in: MarkerReportOutcome (a host reads an outcome it
does not recognize as a refusal) and ReportMarkerResponse.reason.
The docs say the fields arrive in v0.33.0, assuming that is the next tag. Correct
them if you cut a different one.
Needs a release before silo-server can depend on it; the host-side work is
blocked on the tag, not on this branch.
Downstream coordination
silo-server: the report operation, per-segment reportability in its marker
responses, and the viewer's opt-in as an ordinary user setting. Waiting on the
release.
Other marker providers: nothing. A provider that does not serve the service is
simply not reportable, and keeps working as it does today.
Validation
go test ./... passes, including the new coverage: the report round trip
carries identity, numbering, and segment; season_number keeps unset, zero,
and nonzero apart across a wire round trip; a provider built before the service
answers Unimplemented; the explicit option registers the service for a
provider that does not implement it; nothing is registered without a server,
and a typed-nil server is not one; and MarkerProvider keeps exactly FetchMarkers, SubmitMarker, and GetMarkerProviderStats.
go vet ./... clean. The four examples/ builds pass.
make proto needs a protoc binary this environment does not have, so the
generation ran as buf generate with the pinned plugin versions in the
Makefile (protoc-gen-go v1.36.11, protoc-gen-go-grpc v1.6.1). Only marker_provider.pb.go and marker_provider_grpc.pb.go changed, and a second
run left both untouched.
gofmt -l . reports pkg/pluginsdk/runtime/scan_source_test.go, unchanged by
this branch and left alone.
Response to review
Two automated reviewers read the first revision. All six findings are fixed and
answered inline; the later passes are green.
A report could not tell an omitted season from Specials (Silo Kody, high).
Real, and fixed: season_number is now optional, with a round-trip test for
unset, zero, and a nonzero season. The host sends it for an episode, zero
included, and leaves it unset for a movie.
A typed-nil server could be registered (Silo Kody, high, and the same
finding at medium for the auth services). Real, and fixed once for all of them: resolveService now rejects a typed-nil from the interface assertion as well
as from the option, and the auth and marker resolution share it.
The service comment did not name its first release (Silo Kody, low). Fixed:
it says v0.33.0, matching both docs, so all three move together if the tag
differs.
The compatibility doc and the proto disagreed about an unknown outcome
(CodeRabbit, minor). Real, and the doc was right: Unimplemented is what means
"cannot report", while an outcome a host does not recognize came from a
provider that did answer, so it reads as a refusal. The proto comment now says
that.
The season test did not pin the field's wire metadata (Silo Kody, high,
second pass). Real: a switch to sint32, or dropping optional, keeps the Go
pointer and changes the contract. The test now asserts the descriptor kind,
cardinality, and field number.
AI Disclosure
Harness: Hermes Agent
Tool(s): Hermes Agent, GitHub CLI
Model(s): deepseek/deepseek-v4.1-flash
Involvement: Fully AI-generated, human verified
Adversarial review: Silo Kody and CodeRabbit reviewed each revision and raised
the six findings answered above; each was verified against the code before the
fix. Kody's pass on the final commit is green. No independent adversarial
review beyond those two has run for this branch.
A provider can be wrong, and nothing in the contract lets the host pass a
viewer's complaint back to it. A plugin route cannot carry this across
clients: plugin-content routes are a browser surface, and each one is one
plugin's own API.
Adds the separate MarkerReporting service so the released MarkerProvider
server interface keeps its three methods, MarkerSegment.reportable so a
provider says when it would accept a report, and an outcome that keeps a
settled repeat apart from a refusal.
The plugin SDK adds a separate MarkerReporting service, a MarkerSegment.reportable field, runtime registration and client access, tests, and documentation for reporting and compatibility.
Changes: Marker reporting
Layer / File(s)
Summary
Reporting contract and compatibility proto/silo/plugin/v1/marker_provider.proto, docs/marker-provider.md, docs/compatibility.md, README.md
The proto adds the reporting service, request and response types, outcomes, and segment reportability. The documentation describes report handling and compatibility behavior.
Runtime registration and client access pkg/pluginsdk/runtime/runtime.go, pkg/pluginsdk/runtime/serve_manifest.go
The runtime can register an optional reporting server, resolve it from a provider or explicit option, and expose a reporting client.
sequenceDiagram
participant Caller as SDK caller
participant Connection as gRPC connection
participant Server as MarkerReportingServer
Caller->>Connection: Call ReportMarker
Connection->>Server: Dispatch ReportMarker request
Server-->>Connection: Return ReportMarker response
Connection-->>Caller: Return response
Loading
Suggested reviewers:quick104, rhainland
Merge Risk: Low · up to d801d
The compatibility guide gives hosts different handling for an unknown report outcome than the protocol definition does. This could lead host implementers to the wrong behavior. The runtime change is additive and tested, so the risk is low; fix the doc sentence before or soon after merge.
Security architecture risk: Minimal · up to d801d
The reporting API preserves existing provider interfaces and defaults unsupported integrations to no reporting. The inspected change establishes no introduced security-control bypass or material failure-containment regression. Production authorization and report persistence still depend on the host and provider implementations.
Retained concerns
No architecture-level concerns identified.
Security review details
Security Blast Radius
inferred — The new operation can affect a provider's external report records under its configured service account. Its payload targets a media item or file and segment, but effective account-wide exposure, rate limits and downstream effects depend on the provider implementation; the RPC is not evidence of a new unauthenticated public network endpoint.
Trust Boundaries and Controls
observed — The intended trust transition is from a viewer complaint to host-resolved identity, then to the supplying provider over the existing plugin connection. The SDK forwards the request and applicable gRPC interceptor handling; it does not implement viewer authorization or verify the host's item-to-provider binding.
Resilience and Maintainability Implications
observed — The contract distinguishes settled duplicate reports, refusals with no recorded report, missing provider state and retry-later errors. It does not establish atomicity, concurrent deduplication, cancellation-after-commit, or recovery guarantees after an ambiguous timeout. The inspected SDK path delegates the side effect to the provider, so production enforcement of those invariants remains unverified rather than demonstrated to fail.
Hardening Proposals
proposed — For downstream implementations, make report-time authorization, supplying-provider binding and eligibility checks explicit, and document whether a timed-out report can be retried safely. Treat fetch-time reportability as advisory rather than as authorization or a reservation.
Pre-merge checks: 4
Check name
Status
Explanation
Title check
The title names the main change: a marker provider can report an incorrect segment. The changeset adds a separate MarkerReporting service with a ReportMarker RPC, the reportable field on MarkerSegment…
Linked Issues check
Issue #69 is the only directly linked active issue, so its coding requirements apply. The reviewable changes meet each one:
1. Separate service: proto/silo/plugin/v1/marker_provider.proto adds a `M…
Out of Scope Changes check
Every reviewed change maps to issue #69 or to supporting work for it:
- marker_provider.proto: the new service, messages, enum, and reportable field, all required by the issue. - runtime.go, `s…
Description check
The description is specific to the changeset. It explains the problem (a marker provider cannot be told a segment is wrong), the approach (a separate MarkerReporting service with ReportMarker, the Mar…
Full details: Title check
Explanation
The title names the main change: a marker provider can report an incorrect segment. The changeset adds a separate MarkerReporting service with a ReportMarker RPC, the reportable field on MarkerSegment, and runtime registration, all of which match the title's scope. The title uses the conventional feat(scope) form and stays under one line.
Full details: Linked Issues check
Explanation
Issue #69 is the only directly linked active issue, so its coding requirements apply. The reviewable changes meet each one:
Separate service: proto/silo/plugin/v1/marker_provider.proto adds a MarkerReporting service with ReportMarker. MarkerProvider is not changed, which the summary and the PR's test description both state.
Request identity and segment kind: ReportMarkerRequest carries the fetch identity fields (item_type, external_ids, season_number, episode_number, episode_external_ids, episode_numbering, file_hash, file_size, and similar) plus segment.
Outcomes and reason: MarkerReportOutcome has REPORTED, ALREADY_REPORTED, and REFUSED values, and ReportMarkerResponse has reason and detail.
Per-segment reportability: bool reportable = 9 is added to MarkerSegment.
Runtime registration: WithMarkerReporting in serve_manifest.go, automatic registration through resolveService in runtime.go when the marker provider also implements MarkerReportingServer, and Client.MarkerReporting().
Tests: marker_reporting_test.go and marker_reporting_options_test.go cover the round trip, the Unimplemented response for legacy providers, option registration, the no-server case, and the three-method MarkerProvider surface.
Caveat: the generated marker_provider.pb.go and marker_provider_grpc.pb.go are excluded by !**/*.pb.go. The runtime wiring compiles only against those files. The contract is established from the reviewable .proto, and the wiring from runtime.go. Build and test results are author-reported and were not independently verified.
Non-coding items (downstream silo-server and TheIntroDB work, release tagging) are not assessed.
Full details: Out of Scope Changes check
Explanation
Every reviewed change maps to issue #69 or to supporting work for it:
marker_provider.proto: the new service, messages, enum, and reportable field, all required by the issue.
runtime.go, serve_manifest.go: registration and client accessor for the new service, required by the issue's runtime contract.
marker_reporting_test.go, marker_reporting_options_test.go: tests for the new behavior.
docs/marker-provider.md, docs/compatibility.md, README.md: documentation of the new service and its compatibility behavior, which the issue's compatibility section calls for.
No unrelated changes appear in the summary. The gofmt item in the PR description concerns a file the PR does not change. The generated .pb.go files are excluded from review and were not assessed.
Full details: Description check
Explanation
The description is specific to the changeset. It explains the problem (a marker provider cannot be told a segment is wrong), the approach (a separate MarkerReporting service with ReportMarker, the MarkerSegment.reportable field, and MarkerReportOutcome), the runtime WithMarkerReporting option and MarkerReporting() accessor, compatibility impact, validation, and downstream coordination. It matches the raw summary of the proto, runtime, and docs changes.
Finishing Touches
Generate unit tests (beta)
Create a new PR
Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.
…e servers
season_number in ReportMarkerRequest is optional: unset means the host could
not place the episode in a season, and season zero is Specials. resolveService
now also rejects a typed-nil capability server, so neither the auth services nor
marker reporting can register a nil pointer. The service comment gains its first
release and the same reading of an unknown outcome the docs use.
silo-triageBot
added
size/XXL
1000–2999 added + deleted lines (all files); change volume, not priority.
and removed
size/XL
500–999 added + deleted lines (all files); change volume, not priority.
labels
Nov 15, 2026
Asserts the descriptor kind and explicit presence, not only the field number
and the Go pointer: a change to sint32 or to a plain int32 keeps the Go type and
changes the wire contract.
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 settingsReview Options
The following review options are enabled or disabled:
Options
Enabled
Bug
✅
Performance
✅
Security
✅
Business Logic
❌
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
enhancementNew feature or requestgoPull requests that update go codesize/XXL1000–2999 added + deleted lines (all files); change volume, not priority.
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
Closes #69
A marker provider can be wrong, and the contract gives the host no way to say so.
TheIntroDB serves an intro range that does not match the file; the only place to
flag it is the service's own website, so the viewer leaves the player, finds the
title and the episode again, and flags it there.
A provider cannot fix this from outside the contract. An
http_routes.v1routeis a browser surface — native clients do not use the plugin-content mounts — and
it is one plugin's own API, so every other marker provider repeats the work and
every client learns each plugin's route and body shape. A route also has no idea
what the host knows, so a client that addresses the wrong item, or the wrong
episode of the right item, sends a flag that settles on the service and cannot be
taken back. The shape for this is under review in
Silo-Server/silo-server#3085.
Approach
Reporting becomes part of
marker_provider.v1, in three additions:MarkerReportingservice withReportMarker. Adding an RPC toMarkerProviderwould add a method to its released Go server interface andbreak providers that implement it directly, which
docs/compatibility.mdalready rules out. A plugin that does not serve this one answers
Unimplemented, and hosts read that as "this provider cannot report".ReportMarkerRequestcarries the same identity a fetch carries, includingepisode_numbering, plus the segment kind. No bounds: a report is a complaintthat a segment is wrong, not a replacement to store. Its
season_numberisoptional, because on this contract an unset season means "the host could notplace the episode in one" and zero is Specials.
MarkerSegment.reportable, so the provider answers at fetch time whether itwould take a report for that segment now. For a provider that reports through
a shared credential that is "while the operator has configured it" — the
provider decides, so a host never infers this from config entry names.
MarkerReportOutcomekeeps reported, already reported, and refused apart.Already reported is settled, not a failure, which matters because services
commonly key one report per account per item.
The runtime registers the service through a new
WithMarkerReportingoption, oron its own when the
MarkerProviderserver also implementsMarkerReportingServer— the same patternAuthProviderChecksandConfigurationChecksuse.runtime.Clientgains aMarkerReporting()accessor.Compatibility and release impact
Additive.
MarkerProvider,CapabilityServers,ServeConfig, andserveManifestOptionskeep their shapes: the service reaches the plugin setthrough
optionalServices, so an unkeyedCapabilityServersliteral compilesexactly as before. The new tests pin both facts, including that
MarkerProviderstill has its three methods.Two open vocabularies go in:
MarkerReportOutcome(a host reads an outcome itdoes not recognize as a refusal) and
ReportMarkerResponse.reason.The docs say the fields arrive in v0.33.0, assuming that is the next tag. Correct
them if you cut a different one.
Needs a release before
silo-servercan depend on it; the host-side work isblocked on the tag, not on this branch.
Downstream coordination
silo-server: the report operation, per-segment reportability in its markerresponses, and the viewer's opt-in as an ordinary user setting. Waiting on the
release.
silo-plugin-markers-theintrodb: implements the service in place of its ownhttp_routes.v1report route(feat: report an incorrect segment using the server's configured key silo-plugin-markers-theintrodb#14).
simply not reportable, and keeps working as it does today.
Validation
go test ./...passes, including the new coverage: the report round tripcarries identity, numbering, and segment;
season_numberkeeps unset, zero,and nonzero apart across a wire round trip; a provider built before the service
answers
Unimplemented; the explicit option registers the service for aprovider that does not implement it; nothing is registered without a server,
and a typed-nil server is not one; and
MarkerProviderkeeps exactlyFetchMarkers,SubmitMarker, andGetMarkerProviderStats.go vet ./...clean. The fourexamples/builds pass.make protoneeds aprotocbinary this environment does not have, so thegeneration ran as
buf generatewith the pinned plugin versions in theMakefile (
protoc-gen-gov1.36.11,protoc-gen-go-grpcv1.6.1). Onlymarker_provider.pb.goandmarker_provider_grpc.pb.gochanged, and a secondrun left both untouched.
gofmt -l .reportspkg/pluginsdk/runtime/scan_source_test.go, unchanged bythis branch and left alone.
Response to review
Two automated reviewers read the first revision. All six findings are fixed and
answered inline; the later passes are green.
Real, and fixed:
season_numberis nowoptional, with a round-trip test forunset, zero, and a nonzero season. The host sends it for an episode, zero
included, and leaves it unset for a movie.
finding at medium for the auth services). Real, and fixed once for all of them:
resolveServicenow rejects a typed-nil from the interface assertion as wellas from the option, and the auth and marker resolution share it.
it says v0.33.0, matching both docs, so all three move together if the tag
differs.
(CodeRabbit, minor). Real, and the doc was right:
Unimplementedis what means"cannot report", while an outcome a host does not recognize came from a
provider that did answer, so it reads as a refusal. The proto comment now says
that.
second pass). Real: a switch to
sint32, or droppingoptional, keeps the Gopointer and changes the contract. The test now asserts the descriptor kind,
cardinality, and field number.
AI Disclosure
the six findings answered above; each was verified against the code before the
fix. Kody's pass on the final commit is green. No independent adversarial
review beyond those two has run for this branch.