diff --git a/README.md b/README.md index 0a6bc06..a225400 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/docs/compatibility.md b/docs/compatibility.md index eac9fce..e9626b3 100644 --- a/docs/compatibility.md +++ b/docs/compatibility.md @@ -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 @@ -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. + `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 diff --git a/docs/marker-provider.md b/docs/marker-provider.md index 2f835cb..117c7ac 100644 --- a/docs/marker-provider.md +++ b/docs/marker-provider.md @@ -90,6 +90,42 @@ 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 @@ -97,3 +133,12 @@ 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. diff --git a/pkg/pluginproto/silo/plugin/v1/marker_provider.pb.go b/pkg/pluginproto/silo/plugin/v1/marker_provider.pb.go index cab3ceb..b1d7b03 100644 --- a/pkg/pluginproto/silo/plugin/v1/marker_provider.pb.go +++ b/pkg/pluginproto/silo/plugin/v1/marker_provider.pb.go @@ -22,6 +22,62 @@ const ( _ = protoimpl.EnforceVersion(protoimpl.MaxVersion - 20) ) +type MarkerReportOutcome int32 + +const ( + MarkerReportOutcome_MARKER_REPORT_OUTCOME_UNSPECIFIED MarkerReportOutcome = 0 + MarkerReportOutcome_MARKER_REPORT_OUTCOME_REPORTED MarkerReportOutcome = 1 + // The provider already holds this report, for example because the service + // keys one report per account per item. Settled, not a failure. + MarkerReportOutcome_MARKER_REPORT_OUTCOME_ALREADY_REPORTED MarkerReportOutcome = 2 + // The provider declined and the report was not recorded. reason and detail + // say why; the caller may report again later only if reason says so. + MarkerReportOutcome_MARKER_REPORT_OUTCOME_REFUSED MarkerReportOutcome = 3 +) + +// Enum value maps for MarkerReportOutcome. +var ( + MarkerReportOutcome_name = map[int32]string{ + 0: "MARKER_REPORT_OUTCOME_UNSPECIFIED", + 1: "MARKER_REPORT_OUTCOME_REPORTED", + 2: "MARKER_REPORT_OUTCOME_ALREADY_REPORTED", + 3: "MARKER_REPORT_OUTCOME_REFUSED", + } + MarkerReportOutcome_value = map[string]int32{ + "MARKER_REPORT_OUTCOME_UNSPECIFIED": 0, + "MARKER_REPORT_OUTCOME_REPORTED": 1, + "MARKER_REPORT_OUTCOME_ALREADY_REPORTED": 2, + "MARKER_REPORT_OUTCOME_REFUSED": 3, + } +) + +func (x MarkerReportOutcome) Enum() *MarkerReportOutcome { + p := new(MarkerReportOutcome) + *p = x + return p +} + +func (x MarkerReportOutcome) String() string { + return protoimpl.X.EnumStringOf(x.Descriptor(), protoreflect.EnumNumber(x)) +} + +func (MarkerReportOutcome) Descriptor() protoreflect.EnumDescriptor { + return file_silo_plugin_v1_marker_provider_proto_enumTypes[0].Descriptor() +} + +func (MarkerReportOutcome) Type() protoreflect.EnumType { + return &file_silo_plugin_v1_marker_provider_proto_enumTypes[0] +} + +func (x MarkerReportOutcome) Number() protoreflect.EnumNumber { + return protoreflect.EnumNumber(x) +} + +// Deprecated: Use MarkerReportOutcome.Descriptor instead. +func (MarkerReportOutcome) EnumDescriptor() ([]byte, []int) { + return file_silo_plugin_v1_marker_provider_proto_rawDescGZIP(), []int{0} +} + type MarkerExternalIDs struct { state protoimpl.MessageState `protogen:"open.v1"` TmdbId string `protobuf:"bytes,1,opt,name=tmdb_id,json=tmdbId,proto3" json:"tmdb_id,omitempty"` @@ -252,7 +308,17 @@ type MarkerSegment struct { Metadata *structpb.Struct `protobuf:"bytes,7,opt,name=metadata,proto3" json:"metadata,omitempty"` // The provider asserts the item has no segment of this kind. start_seconds // and end_seconds are unset; confidence applies to the absence. - Absent bool `protobuf:"varint,8,opt,name=absent,proto3" json:"absent,omitempty"` + Absent bool `protobuf:"varint,8,opt,name=absent,proto3" json:"absent,omitempty"` + // The provider would accept a report for this segment now, so a host may + // offer a client a control that says the segment is wrong. A provider sets it + // per segment and only when it really would: a provider that reports through + // a service credential sets it only while that credential is configured. + // + // Plain bool, so a host that predates the field reads false and a plugin that + // predates it sends false. Absence and zero mean the same thing here: not + // reportable, which is also what a host must assume for a provider that does + // not serve MarkerReporting. + Reportable bool `protobuf:"varint,9,opt,name=reportable,proto3" json:"reportable,omitempty"` unknownFields protoimpl.UnknownFields sizeCache protoimpl.SizeCache } @@ -343,6 +409,13 @@ func (x *MarkerSegment) GetAbsent() bool { return false } +func (x *MarkerSegment) GetReportable() bool { + if x != nil { + return x.Reportable + } + return false +} + type FetchMarkersResponse struct { state protoimpl.MessageState `protogen:"open.v1"` Markers []*MarkerSegment `protobuf:"bytes,1,rep,name=markers,proto3" json:"markers,omitempty"` @@ -788,6 +861,226 @@ func (x *MarkerProviderStatsResponse) GetMetadata() *structpb.Struct { return nil } +// The item fields follow FetchMarkersRequest, because a report is about the +// markers the host fetched for the same item. external_ids names the title, +// season_number and episode_number place the episode in it in the host +// catalog's numbering, and episode_numbering is the external ID key of the +// provider whose numbering the host used. A provider that reads season and +// episode in its own numbering must translate them by that key, the same way it +// does for a fetch: the numbers alone can name a different episode. +type ReportMarkerRequest struct { + state protoimpl.MessageState `protogen:"open.v1"` + ItemType string `protobuf:"bytes,1,opt,name=item_type,json=itemType,proto3" json:"item_type,omitempty"` // "movie" | "episode" + ExternalIds *MarkerExternalIDs `protobuf:"bytes,2,opt,name=external_ids,json=externalIds,proto3" json:"external_ids,omitempty"` + // Season in the host catalog's numbering, and presence is significant: unset + // means the host could not place the episode in a season, while an explicit + // zero is Specials. A movie leaves it unset. A provider that cannot tell the + // two apart may report the wrong episode, so refuse rather than guess. + SeasonNumber *int32 `protobuf:"varint,3,opt,name=season_number,json=seasonNumber,proto3,oneof" json:"season_number,omitempty"` + EpisodeNumber int32 `protobuf:"varint,4,opt,name=episode_number,json=episodeNumber,proto3" json:"episode_number,omitempty"` + Segment string `protobuf:"bytes,5,opt,name=segment,proto3" json:"segment,omitempty"` // "intro" | "credits" | "recap" | "preview" + DurationSeconds float64 `protobuf:"fixed64,6,opt,name=duration_seconds,json=durationSeconds,proto3" json:"duration_seconds,omitempty"` + EpisodeExternalIds *MarkerExternalIDs `protobuf:"bytes,7,opt,name=episode_external_ids,json=episodeExternalIds,proto3" json:"episode_external_ids,omitempty"` + EpisodeTitle string `protobuf:"bytes,8,opt,name=episode_title,json=episodeTitle,proto3" json:"episode_title,omitempty"` + EpisodeNumbering string `protobuf:"bytes,9,opt,name=episode_numbering,json=episodeNumbering,proto3" json:"episode_numbering,omitempty"` + // The file the viewer was watching, as in FetchMarkersRequest. A report is + // about one copy of the media, so a provider that keys reports by file can + // use them; a provider that keys them by media ignores them. + FileHash string `protobuf:"bytes,10,opt,name=file_hash,json=fileHash,proto3" json:"file_hash,omitempty"` + FileSize int64 `protobuf:"varint,11,opt,name=file_size,json=fileSize,proto3" json:"file_size,omitempty"` + Metadata *structpb.Struct `protobuf:"bytes,12,opt,name=metadata,proto3" json:"metadata,omitempty"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache +} + +func (x *ReportMarkerRequest) Reset() { + *x = ReportMarkerRequest{} + mi := &file_silo_plugin_v1_marker_provider_proto_msgTypes[8] + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + ms.StoreMessageInfo(mi) +} + +func (x *ReportMarkerRequest) String() string { + return protoimpl.X.MessageStringOf(x) +} + +func (*ReportMarkerRequest) ProtoMessage() {} + +func (x *ReportMarkerRequest) ProtoReflect() protoreflect.Message { + mi := &file_silo_plugin_v1_marker_provider_proto_msgTypes[8] + if x != nil { + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + if ms.LoadMessageInfo() == nil { + ms.StoreMessageInfo(mi) + } + return ms + } + return mi.MessageOf(x) +} + +// Deprecated: Use ReportMarkerRequest.ProtoReflect.Descriptor instead. +func (*ReportMarkerRequest) Descriptor() ([]byte, []int) { + return file_silo_plugin_v1_marker_provider_proto_rawDescGZIP(), []int{8} +} + +func (x *ReportMarkerRequest) GetItemType() string { + if x != nil { + return x.ItemType + } + return "" +} + +func (x *ReportMarkerRequest) GetExternalIds() *MarkerExternalIDs { + if x != nil { + return x.ExternalIds + } + return nil +} + +func (x *ReportMarkerRequest) GetSeasonNumber() int32 { + if x != nil && x.SeasonNumber != nil { + return *x.SeasonNumber + } + return 0 +} + +func (x *ReportMarkerRequest) GetEpisodeNumber() int32 { + if x != nil { + return x.EpisodeNumber + } + return 0 +} + +func (x *ReportMarkerRequest) GetSegment() string { + if x != nil { + return x.Segment + } + return "" +} + +func (x *ReportMarkerRequest) GetDurationSeconds() float64 { + if x != nil { + return x.DurationSeconds + } + return 0 +} + +func (x *ReportMarkerRequest) GetEpisodeExternalIds() *MarkerExternalIDs { + if x != nil { + return x.EpisodeExternalIds + } + return nil +} + +func (x *ReportMarkerRequest) GetEpisodeTitle() string { + if x != nil { + return x.EpisodeTitle + } + return "" +} + +func (x *ReportMarkerRequest) GetEpisodeNumbering() string { + if x != nil { + return x.EpisodeNumbering + } + return "" +} + +func (x *ReportMarkerRequest) GetFileHash() string { + if x != nil { + return x.FileHash + } + return "" +} + +func (x *ReportMarkerRequest) GetFileSize() int64 { + if x != nil { + return x.FileSize + } + return 0 +} + +func (x *ReportMarkerRequest) GetMetadata() *structpb.Struct { + if x != nil { + return x.Metadata + } + return nil +} + +type ReportMarkerResponse struct { + state protoimpl.MessageState `protogen:"open.v1"` + Outcome MarkerReportOutcome `protobuf:"varint,1,opt,name=outcome,proto3,enum=silo.plugin.v1.MarkerReportOutcome" json:"outcome,omitempty"` + // Open vocabulary explaining a REFUSED outcome, for example + // "segment_not_reportable" or "unsupported_media". A host that does not + // recognize a value reads it as a plain refusal and shows the viewer that the + // provider would not take the report. + Reason string `protobuf:"bytes,2,opt,name=reason,proto3" json:"reason,omitempty"` + // What to tell the viewer or the administrator about a refusal, in the + // provider's own words. Never carries a credential. + Detail string `protobuf:"bytes,3,opt,name=detail,proto3" json:"detail,omitempty"` + Metadata *structpb.Struct `protobuf:"bytes,4,opt,name=metadata,proto3" json:"metadata,omitempty"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache +} + +func (x *ReportMarkerResponse) Reset() { + *x = ReportMarkerResponse{} + mi := &file_silo_plugin_v1_marker_provider_proto_msgTypes[9] + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + ms.StoreMessageInfo(mi) +} + +func (x *ReportMarkerResponse) String() string { + return protoimpl.X.MessageStringOf(x) +} + +func (*ReportMarkerResponse) ProtoMessage() {} + +func (x *ReportMarkerResponse) ProtoReflect() protoreflect.Message { + mi := &file_silo_plugin_v1_marker_provider_proto_msgTypes[9] + if x != nil { + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + if ms.LoadMessageInfo() == nil { + ms.StoreMessageInfo(mi) + } + return ms + } + return mi.MessageOf(x) +} + +// Deprecated: Use ReportMarkerResponse.ProtoReflect.Descriptor instead. +func (*ReportMarkerResponse) Descriptor() ([]byte, []int) { + return file_silo_plugin_v1_marker_provider_proto_rawDescGZIP(), []int{9} +} + +func (x *ReportMarkerResponse) GetOutcome() MarkerReportOutcome { + if x != nil { + return x.Outcome + } + return MarkerReportOutcome_MARKER_REPORT_OUTCOME_UNSPECIFIED +} + +func (x *ReportMarkerResponse) GetReason() string { + if x != nil { + return x.Reason + } + return "" +} + +func (x *ReportMarkerResponse) GetDetail() string { + if x != nil { + return x.Detail + } + return "" +} + +func (x *ReportMarkerResponse) GetMetadata() *structpb.Struct { + if x != nil { + return x.Metadata + } + return nil +} + var File_silo_plugin_v1_marker_provider_proto protoreflect.FileDescriptor const file_silo_plugin_v1_marker_provider_proto_rawDesc = "" + @@ -811,7 +1104,7 @@ const file_silo_plugin_v1_marker_provider_proto_rawDesc = "" + "\tfile_hash\x18\n" + " \x01(\tR\bfileHash\x12\x1b\n" + "\tfile_size\x18\v \x01(\x03R\bfileSize\x12%\n" + - "\x0eaccepts_absent\x18\f \x01(\bR\racceptsAbsent\"\xd1\x02\n" + + "\x0eaccepts_absent\x18\f \x01(\bR\racceptsAbsent\"\xf1\x02\n" + "\rMarkerSegment\x12\x18\n" + "\asegment\x18\x01 \x01(\tR\asegment\x12(\n" + "\rstart_seconds\x18\x02 \x01(\x01H\x00R\fstartSeconds\x88\x01\x01\x12$\n" + @@ -823,7 +1116,10 @@ const file_silo_plugin_v1_marker_provider_proto_rawDesc = "" + "\x10submission_count\x18\x05 \x01(\x05R\x0fsubmissionCount\x12\x1c\n" + "\talgorithm\x18\x06 \x01(\tR\talgorithm\x123\n" + "\bmetadata\x18\a \x01(\v2\x17.google.protobuf.StructR\bmetadata\x12\x16\n" + - "\x06absent\x18\b \x01(\bR\x06absentB\x10\n" + + "\x06absent\x18\b \x01(\bR\x06absent\x12\x1e\n" + + "\n" + + "reportable\x18\t \x01(\bR\n" + + "reportableB\x10\n" + "\x0e_start_secondsB\x0e\n" + "\f_end_seconds\"\x84\x01\n" + "\x14FetchMarkersResponse\x127\n" + @@ -869,11 +1165,38 @@ const file_silo_plugin_v1_marker_provider_proto_rawDesc = "" + "\x0ecurrent_streak\x18\x06 \x01(\x05R\rcurrentStreak\x12\x1f\n" + "\vbest_streak\x18\a \x01(\x05R\n" + "bestStreak\x123\n" + - "\bmetadata\x18\b \x01(\v2\x17.google.protobuf.StructR\bmetadata2\xbc\x02\n" + + "\bmetadata\x18\b \x01(\v2\x17.google.protobuf.StructR\bmetadata\"\xb6\x04\n" + + "\x13ReportMarkerRequest\x12\x1b\n" + + "\titem_type\x18\x01 \x01(\tR\bitemType\x12D\n" + + "\fexternal_ids\x18\x02 \x01(\v2!.silo.plugin.v1.MarkerExternalIDsR\vexternalIds\x12(\n" + + "\rseason_number\x18\x03 \x01(\x05H\x00R\fseasonNumber\x88\x01\x01\x12%\n" + + "\x0eepisode_number\x18\x04 \x01(\x05R\repisodeNumber\x12\x18\n" + + "\asegment\x18\x05 \x01(\tR\asegment\x12)\n" + + "\x10duration_seconds\x18\x06 \x01(\x01R\x0fdurationSeconds\x12S\n" + + "\x14episode_external_ids\x18\a \x01(\v2!.silo.plugin.v1.MarkerExternalIDsR\x12episodeExternalIds\x12#\n" + + "\repisode_title\x18\b \x01(\tR\fepisodeTitle\x12+\n" + + "\x11episode_numbering\x18\t \x01(\tR\x10episodeNumbering\x12\x1b\n" + + "\tfile_hash\x18\n" + + " \x01(\tR\bfileHash\x12\x1b\n" + + "\tfile_size\x18\v \x01(\x03R\bfileSize\x123\n" + + "\bmetadata\x18\f \x01(\v2\x17.google.protobuf.StructR\bmetadataB\x10\n" + + "\x0e_season_number\"\xba\x01\n" + + "\x14ReportMarkerResponse\x12=\n" + + "\aoutcome\x18\x01 \x01(\x0e2#.silo.plugin.v1.MarkerReportOutcomeR\aoutcome\x12\x16\n" + + "\x06reason\x18\x02 \x01(\tR\x06reason\x12\x16\n" + + "\x06detail\x18\x03 \x01(\tR\x06detail\x123\n" + + "\bmetadata\x18\x04 \x01(\v2\x17.google.protobuf.StructR\bmetadata*\xaf\x01\n" + + "\x13MarkerReportOutcome\x12%\n" + + "!MARKER_REPORT_OUTCOME_UNSPECIFIED\x10\x00\x12\"\n" + + "\x1eMARKER_REPORT_OUTCOME_REPORTED\x10\x01\x12*\n" + + "&MARKER_REPORT_OUTCOME_ALREADY_REPORTED\x10\x02\x12!\n" + + "\x1dMARKER_REPORT_OUTCOME_REFUSED\x10\x032\xbc\x02\n" + "\x0eMarkerProvider\x12Y\n" + "\fFetchMarkers\x12#.silo.plugin.v1.FetchMarkersRequest\x1a$.silo.plugin.v1.FetchMarkersResponse\x12Y\n" + "\fSubmitMarker\x12#.silo.plugin.v1.SubmitMarkerRequest\x1a$.silo.plugin.v1.SubmitMarkerResponse\x12t\n" + - "\x16GetMarkerProviderStats\x12-.silo.plugin.v1.GetMarkerProviderStatsRequest\x1a+.silo.plugin.v1.MarkerProviderStatsResponseBPZNgithub.com/Silo-Server/silo-plugin-sdk/pkg/pluginproto/silo/plugin/v1;pluginv1b\x06proto3" + "\x16GetMarkerProviderStats\x12-.silo.plugin.v1.GetMarkerProviderStatsRequest\x1a+.silo.plugin.v1.MarkerProviderStatsResponse2l\n" + + "\x0fMarkerReporting\x12Y\n" + + "\fReportMarker\x12#.silo.plugin.v1.ReportMarkerRequest\x1a$.silo.plugin.v1.ReportMarkerResponseBPZNgithub.com/Silo-Server/silo-plugin-sdk/pkg/pluginproto/silo/plugin/v1;pluginv1b\x06proto3" var ( file_silo_plugin_v1_marker_provider_proto_rawDescOnce sync.Once @@ -887,42 +1210,53 @@ func file_silo_plugin_v1_marker_provider_proto_rawDescGZIP() []byte { return file_silo_plugin_v1_marker_provider_proto_rawDescData } -var file_silo_plugin_v1_marker_provider_proto_msgTypes = make([]protoimpl.MessageInfo, 8) +var file_silo_plugin_v1_marker_provider_proto_enumTypes = make([]protoimpl.EnumInfo, 1) +var file_silo_plugin_v1_marker_provider_proto_msgTypes = make([]protoimpl.MessageInfo, 10) var file_silo_plugin_v1_marker_provider_proto_goTypes = []any{ - (*MarkerExternalIDs)(nil), // 0: silo.plugin.v1.MarkerExternalIDs - (*FetchMarkersRequest)(nil), // 1: silo.plugin.v1.FetchMarkersRequest - (*MarkerSegment)(nil), // 2: silo.plugin.v1.MarkerSegment - (*FetchMarkersResponse)(nil), // 3: silo.plugin.v1.FetchMarkersResponse - (*SubmitMarkerRequest)(nil), // 4: silo.plugin.v1.SubmitMarkerRequest - (*SubmitMarkerResponse)(nil), // 5: silo.plugin.v1.SubmitMarkerResponse - (*GetMarkerProviderStatsRequest)(nil), // 6: silo.plugin.v1.GetMarkerProviderStatsRequest - (*MarkerProviderStatsResponse)(nil), // 7: silo.plugin.v1.MarkerProviderStatsResponse - (*structpb.Struct)(nil), // 8: google.protobuf.Struct + (MarkerReportOutcome)(0), // 0: silo.plugin.v1.MarkerReportOutcome + (*MarkerExternalIDs)(nil), // 1: silo.plugin.v1.MarkerExternalIDs + (*FetchMarkersRequest)(nil), // 2: silo.plugin.v1.FetchMarkersRequest + (*MarkerSegment)(nil), // 3: silo.plugin.v1.MarkerSegment + (*FetchMarkersResponse)(nil), // 4: silo.plugin.v1.FetchMarkersResponse + (*SubmitMarkerRequest)(nil), // 5: silo.plugin.v1.SubmitMarkerRequest + (*SubmitMarkerResponse)(nil), // 6: silo.plugin.v1.SubmitMarkerResponse + (*GetMarkerProviderStatsRequest)(nil), // 7: silo.plugin.v1.GetMarkerProviderStatsRequest + (*MarkerProviderStatsResponse)(nil), // 8: silo.plugin.v1.MarkerProviderStatsResponse + (*ReportMarkerRequest)(nil), // 9: silo.plugin.v1.ReportMarkerRequest + (*ReportMarkerResponse)(nil), // 10: silo.plugin.v1.ReportMarkerResponse + (*structpb.Struct)(nil), // 11: google.protobuf.Struct } var file_silo_plugin_v1_marker_provider_proto_depIdxs = []int32{ - 8, // 0: silo.plugin.v1.MarkerExternalIDs.provider_ids:type_name -> google.protobuf.Struct - 0, // 1: silo.plugin.v1.FetchMarkersRequest.external_ids:type_name -> silo.plugin.v1.MarkerExternalIDs - 8, // 2: silo.plugin.v1.FetchMarkersRequest.metadata:type_name -> google.protobuf.Struct - 0, // 3: silo.plugin.v1.FetchMarkersRequest.episode_external_ids:type_name -> silo.plugin.v1.MarkerExternalIDs - 8, // 4: silo.plugin.v1.MarkerSegment.metadata:type_name -> google.protobuf.Struct - 2, // 5: silo.plugin.v1.FetchMarkersResponse.markers:type_name -> silo.plugin.v1.MarkerSegment - 8, // 6: silo.plugin.v1.FetchMarkersResponse.metadata:type_name -> google.protobuf.Struct - 0, // 7: silo.plugin.v1.SubmitMarkerRequest.external_ids:type_name -> silo.plugin.v1.MarkerExternalIDs - 8, // 8: silo.plugin.v1.SubmitMarkerRequest.metadata:type_name -> google.protobuf.Struct - 0, // 9: silo.plugin.v1.SubmitMarkerRequest.episode_external_ids:type_name -> silo.plugin.v1.MarkerExternalIDs - 8, // 10: silo.plugin.v1.SubmitMarkerResponse.metadata:type_name -> google.protobuf.Struct - 8, // 11: silo.plugin.v1.MarkerProviderStatsResponse.metadata:type_name -> google.protobuf.Struct - 1, // 12: silo.plugin.v1.MarkerProvider.FetchMarkers:input_type -> silo.plugin.v1.FetchMarkersRequest - 4, // 13: silo.plugin.v1.MarkerProvider.SubmitMarker:input_type -> silo.plugin.v1.SubmitMarkerRequest - 6, // 14: silo.plugin.v1.MarkerProvider.GetMarkerProviderStats:input_type -> silo.plugin.v1.GetMarkerProviderStatsRequest - 3, // 15: silo.plugin.v1.MarkerProvider.FetchMarkers:output_type -> silo.plugin.v1.FetchMarkersResponse - 5, // 16: silo.plugin.v1.MarkerProvider.SubmitMarker:output_type -> silo.plugin.v1.SubmitMarkerResponse - 7, // 17: silo.plugin.v1.MarkerProvider.GetMarkerProviderStats:output_type -> silo.plugin.v1.MarkerProviderStatsResponse - 15, // [15:18] is the sub-list for method output_type - 12, // [12:15] is the sub-list for method input_type - 12, // [12:12] is the sub-list for extension type_name - 12, // [12:12] is the sub-list for extension extendee - 0, // [0:12] is the sub-list for field type_name + 11, // 0: silo.plugin.v1.MarkerExternalIDs.provider_ids:type_name -> google.protobuf.Struct + 1, // 1: silo.plugin.v1.FetchMarkersRequest.external_ids:type_name -> silo.plugin.v1.MarkerExternalIDs + 11, // 2: silo.plugin.v1.FetchMarkersRequest.metadata:type_name -> google.protobuf.Struct + 1, // 3: silo.plugin.v1.FetchMarkersRequest.episode_external_ids:type_name -> silo.plugin.v1.MarkerExternalIDs + 11, // 4: silo.plugin.v1.MarkerSegment.metadata:type_name -> google.protobuf.Struct + 3, // 5: silo.plugin.v1.FetchMarkersResponse.markers:type_name -> silo.plugin.v1.MarkerSegment + 11, // 6: silo.plugin.v1.FetchMarkersResponse.metadata:type_name -> google.protobuf.Struct + 1, // 7: silo.plugin.v1.SubmitMarkerRequest.external_ids:type_name -> silo.plugin.v1.MarkerExternalIDs + 11, // 8: silo.plugin.v1.SubmitMarkerRequest.metadata:type_name -> google.protobuf.Struct + 1, // 9: silo.plugin.v1.SubmitMarkerRequest.episode_external_ids:type_name -> silo.plugin.v1.MarkerExternalIDs + 11, // 10: silo.plugin.v1.SubmitMarkerResponse.metadata:type_name -> google.protobuf.Struct + 11, // 11: silo.plugin.v1.MarkerProviderStatsResponse.metadata:type_name -> google.protobuf.Struct + 1, // 12: silo.plugin.v1.ReportMarkerRequest.external_ids:type_name -> silo.plugin.v1.MarkerExternalIDs + 1, // 13: silo.plugin.v1.ReportMarkerRequest.episode_external_ids:type_name -> silo.plugin.v1.MarkerExternalIDs + 11, // 14: silo.plugin.v1.ReportMarkerRequest.metadata:type_name -> google.protobuf.Struct + 0, // 15: silo.plugin.v1.ReportMarkerResponse.outcome:type_name -> silo.plugin.v1.MarkerReportOutcome + 11, // 16: silo.plugin.v1.ReportMarkerResponse.metadata:type_name -> google.protobuf.Struct + 2, // 17: silo.plugin.v1.MarkerProvider.FetchMarkers:input_type -> silo.plugin.v1.FetchMarkersRequest + 5, // 18: silo.plugin.v1.MarkerProvider.SubmitMarker:input_type -> silo.plugin.v1.SubmitMarkerRequest + 7, // 19: silo.plugin.v1.MarkerProvider.GetMarkerProviderStats:input_type -> silo.plugin.v1.GetMarkerProviderStatsRequest + 9, // 20: silo.plugin.v1.MarkerReporting.ReportMarker:input_type -> silo.plugin.v1.ReportMarkerRequest + 4, // 21: silo.plugin.v1.MarkerProvider.FetchMarkers:output_type -> silo.plugin.v1.FetchMarkersResponse + 6, // 22: silo.plugin.v1.MarkerProvider.SubmitMarker:output_type -> silo.plugin.v1.SubmitMarkerResponse + 8, // 23: silo.plugin.v1.MarkerProvider.GetMarkerProviderStats:output_type -> silo.plugin.v1.MarkerProviderStatsResponse + 10, // 24: silo.plugin.v1.MarkerReporting.ReportMarker:output_type -> silo.plugin.v1.ReportMarkerResponse + 21, // [21:25] is the sub-list for method output_type + 17, // [17:21] is the sub-list for method input_type + 17, // [17:17] is the sub-list for extension type_name + 17, // [17:17] is the sub-list for extension extendee + 0, // [0:17] is the sub-list for field type_name } func init() { file_silo_plugin_v1_marker_provider_proto_init() } @@ -932,18 +1266,20 @@ func file_silo_plugin_v1_marker_provider_proto_init() { } file_silo_plugin_v1_marker_provider_proto_msgTypes[2].OneofWrappers = []any{} file_silo_plugin_v1_marker_provider_proto_msgTypes[4].OneofWrappers = []any{} + file_silo_plugin_v1_marker_provider_proto_msgTypes[8].OneofWrappers = []any{} type x struct{} out := protoimpl.TypeBuilder{ File: protoimpl.DescBuilder{ GoPackagePath: reflect.TypeOf(x{}).PkgPath(), RawDescriptor: unsafe.Slice(unsafe.StringData(file_silo_plugin_v1_marker_provider_proto_rawDesc), len(file_silo_plugin_v1_marker_provider_proto_rawDesc)), - NumEnums: 0, - NumMessages: 8, + NumEnums: 1, + NumMessages: 10, NumExtensions: 0, - NumServices: 1, + NumServices: 2, }, GoTypes: file_silo_plugin_v1_marker_provider_proto_goTypes, DependencyIndexes: file_silo_plugin_v1_marker_provider_proto_depIdxs, + EnumInfos: file_silo_plugin_v1_marker_provider_proto_enumTypes, MessageInfos: file_silo_plugin_v1_marker_provider_proto_msgTypes, }.Build() File_silo_plugin_v1_marker_provider_proto = out.File diff --git a/pkg/pluginproto/silo/plugin/v1/marker_provider_grpc.pb.go b/pkg/pluginproto/silo/plugin/v1/marker_provider_grpc.pb.go index 9976cbe..f4953b2 100644 --- a/pkg/pluginproto/silo/plugin/v1/marker_provider_grpc.pb.go +++ b/pkg/pluginproto/silo/plugin/v1/marker_provider_grpc.pb.go @@ -193,3 +193,155 @@ var MarkerProvider_ServiceDesc = grpc.ServiceDesc{ Streams: []grpc.StreamDesc{}, Metadata: "silo/plugin/v1/marker_provider.proto", } + +const ( + MarkerReporting_ReportMarker_FullMethodName = "/silo.plugin.v1.MarkerReporting/ReportMarker" +) + +// MarkerReportingClient is the client API for MarkerReporting service. +// +// For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream. +// +// MarkerReporting is separate from MarkerProvider so adding reporting does not +// add methods to the released MarkerProviderServer Go interface. Added in +// v0.33.0. Register it with runtime.WithMarkerReporting; the SDK runtime also +// registers it when the MarkerProvider server itself implements +// MarkerReportingServer. +// +// A plugin that does not serve it answers Unimplemented, and hosts treat that +// as "this provider cannot report": a client offers no report control for a +// segment the provider did not mark reportable, and a report that arrives +// anyway fails as unsupported rather than as an error. An outcome a host does +// not recognize is a different case: the provider answered, so hosts read that +// as a refusal, which is the one reading that never claims a report was +// recorded. +type MarkerReportingClient interface { + // ReportMarker tells the provider that the segment the host is showing for + // this item is wrong. It is a viewer's complaint about one segment, not a + // submission: it carries no bounds, and the provider decides what its service + // does with it. + // + // The host resolves the item and its numbering itself and calls the provider + // that supplied the segment, so a provider can trust the identity it is + // given. Refusals the plugin classes as faults use gRPC status codes like + // SubmitMarker: InvalidArgument for a request the provider will never accept, + // FailedPrecondition for provider state such as a credential an operator has + // not configured, and ResourceExhausted with RetryInfo when the provider + // wants the caller to try later. + ReportMarker(ctx context.Context, in *ReportMarkerRequest, opts ...grpc.CallOption) (*ReportMarkerResponse, error) +} + +type markerReportingClient struct { + cc grpc.ClientConnInterface +} + +func NewMarkerReportingClient(cc grpc.ClientConnInterface) MarkerReportingClient { + return &markerReportingClient{cc} +} + +func (c *markerReportingClient) ReportMarker(ctx context.Context, in *ReportMarkerRequest, opts ...grpc.CallOption) (*ReportMarkerResponse, error) { + cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...) + out := new(ReportMarkerResponse) + err := c.cc.Invoke(ctx, MarkerReporting_ReportMarker_FullMethodName, in, out, cOpts...) + if err != nil { + return nil, err + } + return out, nil +} + +// MarkerReportingServer is the server API for MarkerReporting service. +// All implementations should embed UnimplementedMarkerReportingServer +// for forward compatibility. +// +// MarkerReporting is separate from MarkerProvider so adding reporting does not +// add methods to the released MarkerProviderServer Go interface. Added in +// v0.33.0. Register it with runtime.WithMarkerReporting; the SDK runtime also +// registers it when the MarkerProvider server itself implements +// MarkerReportingServer. +// +// A plugin that does not serve it answers Unimplemented, and hosts treat that +// as "this provider cannot report": a client offers no report control for a +// segment the provider did not mark reportable, and a report that arrives +// anyway fails as unsupported rather than as an error. An outcome a host does +// not recognize is a different case: the provider answered, so hosts read that +// as a refusal, which is the one reading that never claims a report was +// recorded. +type MarkerReportingServer interface { + // ReportMarker tells the provider that the segment the host is showing for + // this item is wrong. It is a viewer's complaint about one segment, not a + // submission: it carries no bounds, and the provider decides what its service + // does with it. + // + // The host resolves the item and its numbering itself and calls the provider + // that supplied the segment, so a provider can trust the identity it is + // given. Refusals the plugin classes as faults use gRPC status codes like + // SubmitMarker: InvalidArgument for a request the provider will never accept, + // FailedPrecondition for provider state such as a credential an operator has + // not configured, and ResourceExhausted with RetryInfo when the provider + // wants the caller to try later. + ReportMarker(context.Context, *ReportMarkerRequest) (*ReportMarkerResponse, error) +} + +// UnimplementedMarkerReportingServer should be embedded to have +// forward compatible implementations. +// +// NOTE: this should be embedded by value instead of pointer to avoid a nil +// pointer dereference when methods are called. +type UnimplementedMarkerReportingServer struct{} + +func (UnimplementedMarkerReportingServer) ReportMarker(context.Context, *ReportMarkerRequest) (*ReportMarkerResponse, error) { + return nil, status.Error(codes.Unimplemented, "method ReportMarker not implemented") +} +func (UnimplementedMarkerReportingServer) testEmbeddedByValue() {} + +// UnsafeMarkerReportingServer may be embedded to opt out of forward compatibility for this service. +// Use of this interface is not recommended, as added methods to MarkerReportingServer will +// result in compilation errors. +type UnsafeMarkerReportingServer interface { + mustEmbedUnimplementedMarkerReportingServer() +} + +func RegisterMarkerReportingServer(s grpc.ServiceRegistrar, srv MarkerReportingServer) { + // If the following call panics, it indicates UnimplementedMarkerReportingServer was + // embedded by pointer and is nil. This will cause panics if an + // unimplemented method is ever invoked, so we test this at initialization + // time to prevent it from happening at runtime later due to I/O. + if t, ok := srv.(interface{ testEmbeddedByValue() }); ok { + t.testEmbeddedByValue() + } + s.RegisterService(&MarkerReporting_ServiceDesc, srv) +} + +func _MarkerReporting_ReportMarker_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) { + in := new(ReportMarkerRequest) + if err := dec(in); err != nil { + return nil, err + } + if interceptor == nil { + return srv.(MarkerReportingServer).ReportMarker(ctx, in) + } + info := &grpc.UnaryServerInfo{ + Server: srv, + FullMethod: MarkerReporting_ReportMarker_FullMethodName, + } + handler := func(ctx context.Context, req interface{}) (interface{}, error) { + return srv.(MarkerReportingServer).ReportMarker(ctx, req.(*ReportMarkerRequest)) + } + return interceptor(ctx, in, info, handler) +} + +// MarkerReporting_ServiceDesc is the grpc.ServiceDesc for MarkerReporting service. +// It's only intended for direct use with grpc.RegisterService, +// and not to be introspected or modified (even as a copy) +var MarkerReporting_ServiceDesc = grpc.ServiceDesc{ + ServiceName: "silo.plugin.v1.MarkerReporting", + HandlerType: (*MarkerReportingServer)(nil), + Methods: []grpc.MethodDesc{ + { + MethodName: "ReportMarker", + Handler: _MarkerReporting_ReportMarker_Handler, + }, + }, + Streams: []grpc.StreamDesc{}, + Metadata: "silo/plugin/v1/marker_provider.proto", +} diff --git a/pkg/pluginproto/silo/plugin/v1/marker_provider_test.go b/pkg/pluginproto/silo/plugin/v1/marker_provider_test.go index e3e6e75..bfc1714 100644 --- a/pkg/pluginproto/silo/plugin/v1/marker_provider_test.go +++ b/pkg/pluginproto/silo/plugin/v1/marker_provider_test.go @@ -117,3 +117,33 @@ func TestSubmitMarkerRequest_EpisodeIdentityRoundTrips(t *testing.T) { t.Fatalf("decoded episode identity = %+v", &decoded) } } + +// A report tells an omitted season apart from Specials: season zero is +// Specials, and an unset season means the host could not place the episode in +// one. Flattening the two would let a report land on the wrong episode. +func TestReportMarkerRequest_SeasonNumberPreservesPresenceAndSpecials(t *testing.T) { + seasonZero := int32(0) + assertOptionalInt32Presence( + t, + &ReportMarkerRequest{SeasonNumber: &seasonZero}, + &ReportMarkerRequest{}, + func(message proto.Message) *int32 { + return message.(*ReportMarkerRequest).SeasonNumber + }, + ) + assertFieldNumber(t, &ReportMarkerRequest{}, "season_number", 3) + assertOptionalInt32Field(t, &ReportMarkerRequest{}, "season_number", 3) + + seasonFive := int32(5) + data, err := proto.Marshal(&ReportMarkerRequest{SeasonNumber: &seasonFive}) + if err != nil { + t.Fatalf("marshal season five: %v", err) + } + var decoded ReportMarkerRequest + if err := proto.Unmarshal(data, &decoded); err != nil { + t.Fatalf("unmarshal season five: %v", err) + } + if decoded.SeasonNumber == nil || decoded.GetSeasonNumber() != 5 { + t.Fatalf("season five = %v, want present value 5", decoded.SeasonNumber) + } +} diff --git a/pkg/pluginproto/silo/plugin/v1/optional_presence_test.go b/pkg/pluginproto/silo/plugin/v1/optional_presence_test.go index 38c089a..aa91ddf 100644 --- a/pkg/pluginproto/silo/plugin/v1/optional_presence_test.go +++ b/pkg/pluginproto/silo/plugin/v1/optional_presence_test.go @@ -4,8 +4,30 @@ import ( "testing" "google.golang.org/protobuf/proto" + "google.golang.org/protobuf/reflect/protoreflect" ) +// assertOptionalInt32Field pins a field's wire metadata: an int32 field with +// explicit presence at a given number. The Go type and the field number alone +// allow swapping in sint32 or a plain int32, which keeps the same Go pointer and +// changes the contract the wire carries. +func assertOptionalInt32Field(t *testing.T, message protoreflect.ProtoMessage, field string, want protoreflect.FieldNumber) { + t.Helper() + got := message.ProtoReflect().Descriptor().Fields().ByName(protoreflect.Name(field)) + if got == nil { + t.Fatalf("%T descriptor is missing %s", message, field) + } + if got.Number() != want { + t.Fatalf("%T.%s field number = %d, want %d", message, field, got.Number(), want) + } + if got.Kind() != protoreflect.Int32Kind { + t.Fatalf("%T.%s kind = %v, want int32", message, field, got.Kind()) + } + if got.Cardinality() != protoreflect.Optional { + t.Fatalf("%T.%s cardinality = %v, want explicit presence", message, field, got.Cardinality()) + } +} + func assertOptionalInt32Presence(t *testing.T, withZero proto.Message, empty proto.Message, get func(proto.Message) *int32) { t.Helper() diff --git a/pkg/pluginsdk/runtime/marker_reporting_options_test.go b/pkg/pluginsdk/runtime/marker_reporting_options_test.go new file mode 100644 index 0000000..5b6b682 --- /dev/null +++ b/pkg/pluginsdk/runtime/marker_reporting_options_test.go @@ -0,0 +1,110 @@ +package runtime + +import ( + "context" + "testing" + + pluginv1 "github.com/Silo-Server/silo-plugin-sdk/pkg/pluginproto/silo/plugin/v1" + "github.com/Silo-Server/silo-plugin-sdk/pkg/pluginsdk/capability" + "google.golang.org/grpc/codes" + "google.golang.org/grpc/status" +) + +type optionMarkerProvider struct { + pluginv1.UnimplementedMarkerProviderServer +} + +func (optionMarkerProvider) FetchMarkers(context.Context, *pluginv1.FetchMarkersRequest) (*pluginv1.FetchMarkersResponse, error) { + return &pluginv1.FetchMarkersResponse{}, nil +} + +func (optionMarkerProvider) SubmitMarker(context.Context, *pluginv1.SubmitMarkerRequest) (*pluginv1.SubmitMarkerResponse, error) { + return &pluginv1.SubmitMarkerResponse{}, nil +} + +func (optionMarkerProvider) GetMarkerProviderStats(context.Context, *pluginv1.GetMarkerProviderStatsRequest) (*pluginv1.MarkerProviderStatsResponse, error) { + return &pluginv1.MarkerProviderStatsResponse{}, nil +} + +// optionMarkerReporting is registered through the option rather than baked into +// the provider type, which is how a provider can keep the two services apart. +type optionMarkerReporting struct { + pluginv1.UnimplementedMarkerReportingServer +} + +func (optionMarkerReporting) ReportMarker(_ context.Context, req *pluginv1.ReportMarkerRequest) (*pluginv1.ReportMarkerResponse, error) { + return &pluginv1.ReportMarkerResponse{ + Outcome: pluginv1.MarkerReportOutcome_MARKER_REPORT_OUTCOME_REPORTED, + Reason: req.GetSegment(), + }, nil +} + +func markerManifest() *pluginv1.PluginManifest { + return &pluginv1.PluginManifest{ + PluginId: "silo.test", + Version: "1.0.0", + Capabilities: []*pluginv1.CapabilityDescriptor{ + {Type: capability.MarkerProvider, Id: "test"}, + }, + } +} + +func TestManifestServeConfigRegistersMarkerReportingFromOption(t *testing.T) { + cfg, err := manifestServeConfig( + markerManifest(), + CapabilityServers{MarkerProvider: optionMarkerProvider{}}, + WithMarkerReporting(optionMarkerReporting{}), + ) + if err != nil { + t.Fatalf("manifestServeConfig = %v", err) + } + + got, err := serveConfigClient(t, cfg).MarkerReporting().ReportMarker(context.Background(), + &pluginv1.ReportMarkerRequest{Segment: "credits"}) + if err != nil { + t.Fatalf("ReportMarker = %v", err) + } + if got.GetOutcome() != pluginv1.MarkerReportOutcome_MARKER_REPORT_OUTCOME_REPORTED || got.GetReason() != "credits" { + t.Fatalf("response = %v", got) + } +} + +func TestManifestServeConfigSkipsMarkerReportingWithoutAServer(t *testing.T) { + cfg, err := manifestServeConfig(markerManifest(), CapabilityServers{MarkerProvider: optionMarkerProvider{}}) + if err != nil { + t.Fatalf("manifestServeConfig = %v", err) + } + + _, err = serveConfigClient(t, cfg).MarkerReporting().ReportMarker(context.Background(), + &pluginv1.ReportMarkerRequest{Segment: "credits"}) + if status.Code(err) != codes.Unimplemented { + t.Fatalf("ReportMarker code = %v, want Unimplemented (err %v)", status.Code(err), err) + } +} + +// A provider server typed as a nil pointer satisfies the reporting interface, so +// resolution must not hand it to registration: a nil pointer there is a server +// the first call panics on, not a server that answers. +func TestResolveServiceRejectsATypedNilServer(t *testing.T) { + var absent *reportingNilProvider + if got := resolveService[pluginv1.MarkerReportingServer](absent, nil); !isNilServer(got) { + t.Fatalf("resolved %v from a typed-nil provider, want no server", got) + } + + var alsoAbsent *optionMarkerReporting + if got := resolveService[pluginv1.MarkerReportingServer](optionMarkerProvider{}, alsoAbsent); !isNilServer(got) { + t.Fatalf("resolved %v from a typed-nil option, want no server", got) + } + + present := optionMarkerReporting{} + if got := resolveService[pluginv1.MarkerReportingServer](optionMarkerProvider{}, present); isNilServer(got) { + t.Fatal("resolved no server from a present option") + } +} + +// reportingNilProvider implements the reporting service on a pointer receiver, +// which is what makes a typed-nil value satisfy the interface. +type reportingNilProvider struct { + pluginv1.UnimplementedMarkerProviderServer + pluginv1.UnimplementedMarkerReportingServer +} diff --git a/pkg/pluginsdk/runtime/marker_reporting_test.go b/pkg/pluginsdk/runtime/marker_reporting_test.go new file mode 100644 index 0000000..2e773de --- /dev/null +++ b/pkg/pluginsdk/runtime/marker_reporting_test.go @@ -0,0 +1,122 @@ +package runtime_test + +import ( + "context" + "testing" + + pluginv1 "github.com/Silo-Server/silo-plugin-sdk/pkg/pluginproto/silo/plugin/v1" + runtime "github.com/Silo-Server/silo-plugin-sdk/pkg/pluginsdk/runtime" + "google.golang.org/grpc/codes" + "google.golang.org/grpc/status" +) + +// legacyMarkerProvider is a marker server written before reporting existed: it +// serves only the MarkerProvider service. +type legacyMarkerProvider struct { + pluginv1.UnimplementedMarkerProviderServer +} + +func (legacyMarkerProvider) FetchMarkers(context.Context, *pluginv1.FetchMarkersRequest) (*pluginv1.FetchMarkersResponse, error) { + return &pluginv1.FetchMarkersResponse{}, nil +} + +func (legacyMarkerProvider) SubmitMarker(context.Context, *pluginv1.SubmitMarkerRequest) (*pluginv1.SubmitMarkerResponse, error) { + return &pluginv1.SubmitMarkerResponse{}, nil +} + +func (legacyMarkerProvider) GetMarkerProviderStats(context.Context, *pluginv1.GetMarkerProviderStatsRequest) (*pluginv1.MarkerProviderStatsResponse, error) { + return &pluginv1.MarkerProviderStatsResponse{}, nil +} + +// reportingMarkerProvider serves the fetch side and the separate reporting +// service on one type, which is how the SDK expects a provider to add reporting +// without changing the released MarkerProvider interface. +type reportingMarkerProvider struct { + pluginv1.UnimplementedMarkerProviderServer + gotRequest *pluginv1.ReportMarkerRequest +} + +func (reportingMarkerProvider) FetchMarkers(context.Context, *pluginv1.FetchMarkersRequest) (*pluginv1.FetchMarkersResponse, error) { + return &pluginv1.FetchMarkersResponse{}, nil +} + +func (reportingMarkerProvider) SubmitMarker(context.Context, *pluginv1.SubmitMarkerRequest) (*pluginv1.SubmitMarkerResponse, error) { + return &pluginv1.SubmitMarkerResponse{}, nil +} + +func (reportingMarkerProvider) GetMarkerProviderStats(context.Context, *pluginv1.GetMarkerProviderStatsRequest) (*pluginv1.MarkerProviderStatsResponse, error) { + return &pluginv1.MarkerProviderStatsResponse{}, nil +} + +func (p *reportingMarkerProvider) ReportMarker(_ context.Context, req *pluginv1.ReportMarkerRequest) (*pluginv1.ReportMarkerResponse, error) { + p.gotRequest = req + return &pluginv1.ReportMarkerResponse{ + Outcome: pluginv1.MarkerReportOutcome_MARKER_REPORT_OUTCOME_ALREADY_REPORTED, + }, nil +} + +var ( + _ pluginv1.MarkerProviderServer = (*legacyMarkerProvider)(nil) + _ pluginv1.MarkerReportingServer = (*reportingMarkerProvider)(nil) +) + +// The report round trip carries the identity the fetch carries, including the +// numbering the host chose, so a provider can address the same episode a second +// time. +func TestMarkerReportingRoundTripWhenProviderImplementsIt(t *testing.T) { + provider := &reportingMarkerProvider{} + client := dialPlugin(t, runtime.CapabilityServers{Runtime: stubRuntime{}, MarkerProvider: provider}) + + season := int32(5) + got, err := client.MarkerReporting().ReportMarker(context.Background(), &pluginv1.ReportMarkerRequest{ + ItemType: "episode", + ExternalIds: &pluginv1.MarkerExternalIDs{ImdbId: "tt0903747"}, + SeasonNumber: &season, + EpisodeNumber: 14, + Segment: "intro", + EpisodeNumbering: "tvdb", + }) + if err != nil { + t.Fatalf("ReportMarker = %v", err) + } + if got.GetOutcome() != pluginv1.MarkerReportOutcome_MARKER_REPORT_OUTCOME_ALREADY_REPORTED { + t.Fatalf("outcome = %v, want ALREADY_REPORTED", got.GetOutcome()) + } + if provider.gotRequest.GetSegment() != "intro" || provider.gotRequest.GetEpisodeNumbering() != "tvdb" || + provider.gotRequest.GetSeasonNumber() != 5 || provider.gotRequest.GetEpisodeNumber() != 14 { + t.Fatalf("request = %v", provider.gotRequest) + } +} + +// A plugin built before the service existed must answer Unimplemented, which +// hosts read as "this provider cannot report" rather than as a failure. +func TestMarkerReportingUnimplementedForLegacyProvider(t *testing.T) { + client := dialPlugin(t, runtime.CapabilityServers{Runtime: stubRuntime{}, MarkerProvider: legacyMarkerProvider{}}) + + _, err := client.MarkerReporting().ReportMarker(context.Background(), &pluginv1.ReportMarkerRequest{Segment: "intro"}) + if status.Code(err) != codes.Unimplemented { + t.Fatalf("ReportMarker code = %v, want Unimplemented (err %v)", status.Code(err), err) + } +} + +// Reporting lives in its own service, so the released MarkerProvider service +// keeps exactly the three methods plugins already implement. +func TestMarkerProviderServiceGainsNoMethods(t *testing.T) { + services := registeredServices(t, runtime.CapabilityServers{ + Runtime: stubRuntime{}, + MarkerProvider: legacyMarkerProvider{}, + }) + info, ok := services["silo.plugin.v1.MarkerProvider"] + if !ok { + t.Fatalf("MarkerProvider service not registered; got %v", services) + } + want := map[string]bool{"FetchMarkers": true, "SubmitMarker": true, "GetMarkerProviderStats": true} + if len(info.Methods) != len(want) { + t.Fatalf("MarkerProvider methods = %v, want %v", info.Methods, want) + } + for _, method := range info.Methods { + if !want[method.Name] { + t.Fatalf("MarkerProvider gained method %q; report RPCs belong on MarkerReporting", method.Name) + } + } +} diff --git a/pkg/pluginsdk/runtime/runtime.go b/pkg/pluginsdk/runtime/runtime.go index ee1fa5f..be75715 100644 --- a/pkg/pluginsdk/runtime/runtime.go +++ b/pkg/pluginsdk/runtime/runtime.go @@ -95,13 +95,15 @@ type optionalServices struct { authProviderChecks pluginv1.AuthProviderChecksServer networkIdentityAuth pluginv1.NetworkIdentityAuthServer configurationChecks pluginv1.ConfigurationChecksServer + markerReporting pluginv1.MarkerReportingServer } func pluginSetWithOptionalServices(servers CapabilityServers, optional optionalServices) plugin.PluginSet { // Compare fields one by one: == on the struct would panic for a server // whose dynamic type is not comparable. if optional.watchSyncDeviceAuthorization == nil && optional.authProviderChecks == nil && - optional.networkIdentityAuth == nil && optional.configurationChecks == nil { + optional.networkIdentityAuth == nil && optional.configurationChecks == nil && + optional.markerReporting == nil { return DefaultPluginSet(servers) } return plugin.PluginSet{ @@ -143,6 +145,14 @@ func (c *Client) MarkerProvider() pluginv1.MarkerProviderClient { return pluginv1.NewMarkerProviderClient(c.conn) } +// MarkerReporting returns the client for reporting an incorrect segment, the +// separate service a marker provider serves when it accepts reports. Plugins +// built before it existed answer Unimplemented, which hosts read as "this +// provider cannot report". +func (c *Client) MarkerReporting() pluginv1.MarkerReportingClient { + return pluginv1.NewMarkerReportingClient(c.conn) +} + func (c *Client) MediaAnalyzer() pluginv1.MediaAnalyzerClient { return pluginv1.NewMediaAnalyzerClient(c.conn) } @@ -240,10 +250,19 @@ func (p *GRPCPlugin) GRPCServer(broker *plugin.GRPCBroker, server *grpc.Server) // nil pointer passed to the option counts as no server, so the startup checks // in manifestServeConfig catch it instead of the first call panicking. func resolveAuthService[S any](authProvider pluginv1.AuthProviderServer, explicit S) S { + return resolveService(authProvider, explicit) +} + +// resolveService returns the server to register for a service kept out of a +// capability's released server interface: the explicit one from its +// ServeManifest option, else the capability server when it also implements the +// service, else nil. A nil pointer passed to the option counts as no server, so +// a startup check sees it as missing instead of the first call panicking. +func resolveService[S any](capability any, explicit S) S { if !isNilServer(explicit) { return explicit } - if server, ok := authProvider.(S); ok { + if server, ok := capability.(S); ok && !isNilServer(server) { return server } var none S @@ -276,6 +295,11 @@ func (p *GRPCPlugin) registerServers( if p.Servers.MarkerProvider != nil { pluginv1.RegisterMarkerProviderServer(server, p.Servers.MarkerProvider) } + // MarkerReporting lives in its own service so the released + // MarkerProviderServer interface stays unchanged. + if reporting := resolveService(p.Servers.MarkerProvider, optional.markerReporting); reporting != nil { + pluginv1.RegisterMarkerReportingServer(server, reporting) + } if p.Servers.MediaAnalyzer != nil { pluginv1.RegisterMediaAnalyzerServer(server, p.Servers.MediaAnalyzer) } diff --git a/pkg/pluginsdk/runtime/serve_manifest.go b/pkg/pluginsdk/runtime/serve_manifest.go index e6209c0..4a23c12 100644 --- a/pkg/pluginsdk/runtime/serve_manifest.go +++ b/pkg/pluginsdk/runtime/serve_manifest.go @@ -46,6 +46,7 @@ type serveManifestOptions struct { authProviderChecks pluginv1.AuthProviderChecksServer networkIdentityAuth pluginv1.NetworkIdentityAuthServer configurationChecks pluginv1.ConfigurationChecksServer + markerReporting pluginv1.MarkerReportingServer configure ConfigureFunc } @@ -97,6 +98,18 @@ func WithConfigurationChecks(server pluginv1.ConfigurationChecksServer) ServeMan } } +// WithMarkerReporting registers the separate MarkerReporting service, which +// lets a viewer report an incorrect segment to a marker provider. Without it, +// the runtime registers the service only when the MarkerProvider server itself +// implements MarkerReportingServer. Serving it is also what makes +// MarkerSegment.reportable meaningful: a host offers a report control only for +// a segment the provider marked reportable. +func WithMarkerReporting(server pluginv1.MarkerReportingServer) ServeManifestOption { + return func(options *serveManifestOptions) { + options.markerReporting = server + } +} + // WithConfigure delivers Runtime.Configure entries to fn, so a plugin served by // ServeManifestWithOptions can read its settings without writing its own // Runtime server. See ConfigureFunc for what fn may reject. @@ -205,6 +218,9 @@ func manifestServeConfig( return ServeConfig{}, fmt.Errorf("plugin manifest declares %q but no ConfigurationChecks server is registered; pass runtime.WithConfigurationChecks", manifest.ConfigurationCheckKey) } + if isNilServer(resolved.markerReporting) { + resolved.markerReporting = nil + } servers.Runtime = &manifestRuntime{manifest: m, configure: resolved.configure} return ServeConfig{ Servers: servers, @@ -213,6 +229,7 @@ func manifestServeConfig( authProviderChecks: resolved.authProviderChecks, networkIdentityAuth: resolved.networkIdentityAuth, configurationChecks: resolved.configurationChecks, + markerReporting: resolved.markerReporting, }), }, nil } diff --git a/proto/silo/plugin/v1/marker_provider.proto b/proto/silo/plugin/v1/marker_provider.proto index 1e05ce2..2015dc7 100644 --- a/proto/silo/plugin/v1/marker_provider.proto +++ b/proto/silo/plugin/v1/marker_provider.proto @@ -12,6 +12,35 @@ service MarkerProvider { rpc GetMarkerProviderStats(GetMarkerProviderStatsRequest) returns (MarkerProviderStatsResponse); } +// MarkerReporting is separate from MarkerProvider so adding reporting does not +// add methods to the released MarkerProviderServer Go interface. Added in +// v0.33.0. Register it with runtime.WithMarkerReporting; the SDK runtime also +// registers it when the MarkerProvider server itself implements +// MarkerReportingServer. +// +// A plugin that does not serve it answers Unimplemented, and hosts treat that +// as "this provider cannot report": a client offers no report control for a +// segment the provider did not mark reportable, and a report that arrives +// anyway fails as unsupported rather than as an error. An outcome a host does +// not recognize is a different case: the provider answered, so hosts read that +// as a refusal, which is the one reading that never claims a report was +// recorded. +service MarkerReporting { + // ReportMarker tells the provider that the segment the host is showing for + // this item is wrong. It is a viewer's complaint about one segment, not a + // submission: it carries no bounds, and the provider decides what its service + // does with it. + // + // The host resolves the item and its numbering itself and calls the provider + // that supplied the segment, so a provider can trust the identity it is + // given. Refusals the plugin classes as faults use gRPC status codes like + // SubmitMarker: InvalidArgument for a request the provider will never accept, + // FailedPrecondition for provider state such as a credential an operator has + // not configured, and ResourceExhausted with RetryInfo when the provider + // wants the caller to try later. + rpc ReportMarker(ReportMarkerRequest) returns (ReportMarkerResponse); +} + message MarkerExternalIDs { string tmdb_id = 1; string imdb_id = 2; @@ -64,6 +93,16 @@ message MarkerSegment { // The provider asserts the item has no segment of this kind. start_seconds // and end_seconds are unset; confidence applies to the absence. bool absent = 8; + // The provider would accept a report for this segment now, so a host may + // offer a client a control that says the segment is wrong. A provider sets it + // per segment and only when it really would: a provider that reports through + // a service credential sets it only while that credential is configured. + // + // Plain bool, so a host that predates the field reads false and a plugin that + // predates it sends false. Absence and zero mean the same thing here: not + // reportable, which is also what a host must assume for a provider that does + // not serve MarkerReporting. + bool reportable = 9; } message FetchMarkersResponse { @@ -120,3 +159,56 @@ message MarkerProviderStatsResponse { int32 best_streak = 7; google.protobuf.Struct metadata = 8; } + +// The item fields follow FetchMarkersRequest, because a report is about the +// markers the host fetched for the same item. external_ids names the title, +// season_number and episode_number place the episode in it in the host +// catalog's numbering, and episode_numbering is the external ID key of the +// provider whose numbering the host used. A provider that reads season and +// episode in its own numbering must translate them by that key, the same way it +// does for a fetch: the numbers alone can name a different episode. +message ReportMarkerRequest { + string item_type = 1; // "movie" | "episode" + MarkerExternalIDs external_ids = 2; + // Season in the host catalog's numbering, and presence is significant: unset + // means the host could not place the episode in a season, while an explicit + // zero is Specials. A movie leaves it unset. A provider that cannot tell the + // two apart may report the wrong episode, so refuse rather than guess. + optional int32 season_number = 3; + int32 episode_number = 4; + string segment = 5; // "intro" | "credits" | "recap" | "preview" + double duration_seconds = 6; + MarkerExternalIDs episode_external_ids = 7; + string episode_title = 8; + string episode_numbering = 9; + // The file the viewer was watching, as in FetchMarkersRequest. A report is + // about one copy of the media, so a provider that keys reports by file can + // use them; a provider that keys them by media ignores them. + string file_hash = 10; + int64 file_size = 11; + google.protobuf.Struct metadata = 12; +} + +message ReportMarkerResponse { + MarkerReportOutcome outcome = 1; + // Open vocabulary explaining a REFUSED outcome, for example + // "segment_not_reportable" or "unsupported_media". A host that does not + // recognize a value reads it as a plain refusal and shows the viewer that the + // provider would not take the report. + string reason = 2; + // What to tell the viewer or the administrator about a refusal, in the + // provider's own words. Never carries a credential. + string detail = 3; + google.protobuf.Struct metadata = 4; +} + +enum MarkerReportOutcome { + MARKER_REPORT_OUTCOME_UNSPECIFIED = 0; + MARKER_REPORT_OUTCOME_REPORTED = 1; + // The provider already holds this report, for example because the service + // keys one report per account per item. Settled, not a failure. + MARKER_REPORT_OUTCOME_ALREADY_REPORTED = 2; + // The provider declined and the report was not recorded. reason and detail + // say why; the caller may report again later only if reason says so. + MARKER_REPORT_OUTCOME_REFUSED = 3; +}