Skip to content

feat(markers): let a marker provider report an incorrect segment - #70

Open
Pasithea0 wants to merge 3 commits into
Silo-Server:mainfrom
Pasithea0:feat/markers-report-incorrect-segment
Open

Pasithea0 wants to merge 3 commits into
Silo-Server:mainfrom
Pasithea0:feat/markers-report-incorrect-segment

Conversation

@Pasithea0

@Pasithea0 Pasithea0 commented Nov 15, 2026 •

Copy link
Copy Markdown

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.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.
  • silo-plugin-markers-theintrodb: implements the service in place of its own
    http_routes.v1 report route
    (feat: report an incorrect segment using the server's configured key silo-plugin-markers-theintrodb#14).
  • 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.
@silo-triage silo-triage Bot added the size/XL 500–999 added + deleted lines (all files); change volume, not priority. label Nov 15, 2026
@coderabbitai

coderabbitai Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

Explain Change →

Walkthrough

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.
Reporting runtime tests
pkg/pluginsdk/runtime/marker_reporting_options_test.go, pkg/pluginsdk/runtime/marker_reporting_test.go
Tests cover optional service registration, report request handling, unsupported reporting, and the existing MarkerProvider methods.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature · Severity of issue fixed: Medium

Sequence Diagram(s)

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: Passed 4

Check name Status Explanation
Title check Passed 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 Passed 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 Passed 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 Passed 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:

  1. 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.
  2. 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.
  3. Outcomes and reason: MarkerReportOutcome has REPORTED, ALREADY_REPORTED, and REFUSED values, and ReportMarkerResponse has reason and detail.
  4. Per-segment reportability: bool reportable = 9 is added to MarkerSegment.
  5. Runtime registration: WithMarkerReporting in serve_manifest.go, automatic registration through resolveService in runtime.go when the marker provider also implements MarkerReportingServer, and Client.MarkerReporting().
  6. 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

@silo-kody

silo-kody Bot commented Nov 15, 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-triage silo-triage Bot added enhancement New feature or request go Pull requests that update go code labels Nov 15, 2026
Comment thread pkg/pluginsdk/runtime/runtime.go Resolved
Comment thread pkg/pluginsdk/runtime/runtime.go Resolved
Comment thread pkg/pluginsdk/runtime/runtime.go Resolved

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Actionable comments posted: 1

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: d3e6a2e2-952a-485c-abd2-5aafcda8736e
Commits

Reviewing files that changed from the base of the PR and between b82b589 and d801d6f.

Files ignored due to path filters: 2

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

  • README.md
  • docs/compatibility.md
  • docs/marker-provider.md
  • pkg/pluginsdk/runtime/marker_reporting_options_test.go
  • pkg/pluginsdk/runtime/marker_reporting_test.go
  • pkg/pluginsdk/runtime/runtime.go
  • pkg/pluginsdk/runtime/serve_manifest.go
  • proto/silo/plugin/v1/marker_provider.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.

Comment thread docs/compatibility.md Resolved
…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-triage silo-triage Bot 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
@silo-kody

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

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.
@silo-kody

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

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/XXL 1000–2999 added + deleted lines (all files); change volume, not priority.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Let a marker provider report an incorrect segment

1 participant