Skip to content
Open
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
6 changes: 6 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -500,6 +500,12 @@ starting fetch priority and contribution defaults travel in the capability's
`metadata`. See [docs/marker-provider.md](docs/marker-provider.md) for those
keys, the file facts the host sends, and absent segments.

A provider can also accept reports that a segment is wrong: it serves the
separate `MarkerReporting` service and marks the segments it would accept a
report for with `MarkerSegment.reportable`, and the host exposes one report
operation that every client can call. See the same doc for the request, the
outcomes, and what to tell the viewer.

## Network access providers

`network_access_provider.v1` lets a resident plugin give the deployment an
Expand Down
15 changes: 13 additions & 2 deletions docs/compatibility.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,8 +94,8 @@ Adding an RPC to a released service adds a method to its Go server interface,
which breaks plugins that implement the interface directly rather than
embedding the generated `Unimplemented...Server`. New RPCs for a released
capability therefore go in a separate service, such as
`WatchSyncDeviceAuthorizationService`, `AuthProviderChecks` or
`NetworkIdentityAuth`. A plugin that
`WatchSyncDeviceAuthorizationService`, `AuthProviderChecks`,
`NetworkIdentityAuth`, or `MarkerReporting`. A plugin that
does not register the new service answers `Unimplemented`, and hosts treat that
as "not supported". A network provider cannot fall back that way: without
`AuthProviderChecks.CheckAccount`, a person removed from the overlay would stay
Expand Down Expand Up @@ -203,6 +203,17 @@ of 0, `accepts_absent` false, and submissions without `source`, `algorithm`,
true: an older host reads a segment without bounds as covering the whole
file. See [marker-provider.md](marker-provider.md).

`MarkerSegment.reportable` (added in v0.33.0) is a plain bool, so it has no
presence: false means the provider would not accept a report for that segment,
which is also what a host that predates the field reads and what a plugin that
predates it sends. Report RPCs are in the separate `MarkerReporting` service, so
the released `MarkerProviderServer` interface keeps its three methods; a provider
that does not serve the service answers Unimplemented, which a host must treat as
"cannot report" rather than as a failure. `MarkerReportOutcome` and
`ReportMarkerResponse.reason` are open vocabularies: a host reads an outcome it
does not recognize as a refusal, and a reason it does not recognize as a plain
refusal.
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved

`SeasonRecord.backdrop_path` (added in v0.31.0) is a plain string, like
`poster_path`. Empty means the provider has no landscape art for the season,
which is how hosts read every plugin built before the field existed. A host
Expand Down
45 changes: 45 additions & 0 deletions docs/marker-provider.md
Original file line number Diff line number Diff line change
Expand Up @@ -90,10 +90,55 @@ and carries one segment with its bounds. Since v0.30.0 it also carries:
the bounds are unset. Hosts send it only to providers that declare
`supports_absent`.

## Reporting

A segment can be wrong, and the viewer watching it knows first. A provider that
accepts reports serves the separate `MarkerReporting` service, and the host
exposes one operation of its own for it, so every client offers the same control
without knowing which provider supplied the markers.

- `MarkerSegment.reportable` (added in v0.33.0) says, per segment, that the
provider would accept a report for it now. Set it only when that is true: a
provider that reports through a shared service credential sets it only while
the operator has configured that credential. The host draws no report control
for a segment that is not reportable.
- `ReportMarkerRequest` carries the same identity a fetch carries, including
`episode_numbering`, plus the segment kind. It carries no bounds: a report is
a complaint that a segment is wrong, not a replacement to store. Its
`season_number` is `optional`, and presence means what it means everywhere
else in this contract: unset is "the host could not place the episode in a
season", an explicit zero is Specials, and a movie leaves it unset. A provider
that cannot tell those apart may report the wrong episode, so refuse instead of
guessing.
- `ReportMarkerResponse.outcome` is reported, already reported, or refused.
already reported is settled, not a failure: a service that keys one report
per account per item answers it for a repeat, and the viewer is told the
segment is already known about. A refusal carries `reason`, an open
vocabulary, and `detail`, words for the viewer or the administrator.
- Faults the provider classes as errors use gRPC status codes, as `SubmitMarker`
does: InvalidArgument for a request it will never accept, FailedPrecondition
for missing provider state such as an unconfigured credential, and
ResourceExhausted with RetryInfo when the caller should try later.

Register the service with `runtime.WithMarkerReporting`, or implement
`MarkerReportingServer` on the same type as your `MarkerProviderServer` and the
runtime registers it for you. A provider that does not serve it answers
Unimplemented, which hosts read as "this provider cannot report", not as an
error: no client is offered a report control for it.

## Compatibility

All the v0.30.0 fields are additive. A host older than v0.30.0 leaves them
empty: no file facts, `accepts_absent` false, and no `source`, `algorithm`,
`confidence`, or `absent` on submissions. Providers must handle an empty
`file_hash` and a `file_size` of 0, and treat a submission with an empty
`source` as one whose origin is unknown.

Reporting is additive too. `MarkerProvider` and `CapabilityServers` are
unchanged: the report RPC is a separate service so a provider that implements the
released interface directly still compiles. A plugin built before v0.33.0 sends
no `reportable` and serves no `MarkerReporting`, so a host that has both offers
no report control for it; a host built before it ignores the service and reads
`reportable` as false. A host must not offer a report for a segment that came
from a provider it cannot call: treat a provider that does not serve
`MarkerReporting` as unable to report, whatever `reportable` says.
Loading