diff --git a/README.md b/README.md index 0a6bc06..3404f7b 100644 --- a/README.md +++ b/README.md @@ -29,7 +29,7 @@ The SDK ships protobuf contracts for every capability the host understands: - `marker_provider.v1` - `media_analyzer.v1` - `image_resolver.v1` -- `scheduled_task.v1` +- `scheduled_task.v1` (see [docs/scheduled-task.md](docs/scheduled-task.md)) - `event_consumer.v1` - `auth_provider.v1` - `http_routes.v1` diff --git a/docs/scheduled-task.md b/docs/scheduled-task.md new file mode 100644 index 0000000..5db58cf --- /dev/null +++ b/docs/scheduled-task.md @@ -0,0 +1,48 @@ +# Scheduled tasks + +A `scheduled_task.v1` capability is a job the host runs on a schedule. The +host calls `ScheduledTask.Run` with the task's key each time the schedule +fires. When Silo runs several API servers, one of them takes each run; the +others skip it. + +An administrator sets the schedule on the host. Until they do, the host uses +the capability's default: + +```json +{ + "type": "scheduled_task.v1", + "id": "health_check", + "display_name": "Health check", + "scheduled_task": { + "default_trigger": { "type": "interval", "interval_ms": 300000 } + } +} +``` + +| `type` | Fields | Runs | +|---|---|---| +| `interval` | `interval_ms`, from 60000 to 9223372036854 | Every `interval_ms` milliseconds. | +| `daily` | `time_of_day`, `"HH:MM"` | Once a day at that time, in the time zone of the Silo server process (its `TZ`; UTC in the default container). | +| `weekly` | `time_of_day`, `day_of_week` (0 is Sunday) | Once a week, in the same time zone. | +| `startup` | none | Once when Silo starts. Servers that start together share one run. | + +Without a default, a task the administrator hasn't scheduled runs once when +Silo starts. + +Many servers install the same plugin with the same default, so a task that +calls an outside service at `03:00` reaches it from all of them at once. Wait +a random few minutes at the start of `Run`, or pick an unusual time. The trigger type vocabulary is open: a host uses its own +default for a type it doesn't know. + +A host that predates `scheduled_task` ignores it, and runs the task once each +time it starts, only if it drops unknown fields wherever it reads the manifest. +The SDK's `manifest.Load` always has. A Silo host built before +Silo-Server/silo-server#2502 does not: it reads a bare plugin binary's manifest +strictly, and before starting a plugin it compares the installed manifest with +the one the plugin reports, unknown fields included. It refuses to install a +binary that sets `scheduled_task` and refuses to start such a plugin installed +from an archive. + +A task that has to run at a time each user picks, such as a weekly digest +sent in each user's own time zone, can run every hour and decide per user +whether it's time. diff --git a/examples/hello-scheduled-task/README.md b/examples/hello-scheduled-task/README.md index 9e312c2..94ff3ee 100644 --- a/examples/hello-scheduled-task/README.md +++ b/examples/hello-scheduled-task/README.md @@ -7,7 +7,7 @@ It demonstrates: - embedding a manifest template with `//go:embed` - computing the executable checksum at runtime - returning the manifest through `Runtime.GetManifest` -- exposing a `scheduled_task.v1` capability +- exposing a `scheduled_task.v1` capability with a default schedule (daily at 03:00) ## Build diff --git a/examples/hello-scheduled-task/manifest.json b/examples/hello-scheduled-task/manifest.json index 493312d..94ea643 100644 --- a/examples/hello-scheduled-task/manifest.json +++ b/examples/hello-scheduled-task/manifest.json @@ -8,7 +8,10 @@ "type": "scheduled_task.v1", "id": "hello", "display_name": "Hello Task", - "description": "A minimal scheduled task example." + "description": "A minimal scheduled task example.", + "scheduled_task": { + "default_trigger": { "type": "daily", "time_of_day": "03:00" } + } } ] } diff --git a/pkg/pluginproto/silo/plugin/v1/common.pb.go b/pkg/pluginproto/silo/plugin/v1/common.pb.go index 7b6fde1..b8060c0 100644 --- a/pkg/pluginproto/silo/plugin/v1/common.pb.go +++ b/pkg/pluginproto/silo/plugin/v1/common.pb.go @@ -988,6 +988,13 @@ type CapabilityDescriptor struct { // of type "request_router.v1". Optional: an absent descriptor declares no // optional request-router features. RequestRouter *RequestRouterDescriptor `protobuf:"bytes,12,opt,name=request_router,json=requestRouter,proto3" json:"request_router,omitempty"` + // Typed scheduled-task metadata. Optional, and only meaningful on + // capabilities of type "scheduled_task.v1". A host that predates the field + // ignores it only if it drops unknown fields wherever it reads the + // manifest. Silo hosts built before Silo-Server/silo-server#2502 don't, and + // refuse to install or start a plugin that sets it (see + // docs/scheduled-task.md). + ScheduledTask *ScheduledTaskDescriptor `protobuf:"bytes,14,opt,name=scheduled_task,json=scheduledTask,proto3" json:"scheduled_task,omitempty"` unknownFields protoimpl.UnknownFields sizeCache protoimpl.SizeCache } @@ -1106,6 +1113,135 @@ func (x *CapabilityDescriptor) GetRequestRouter() *RequestRouterDescriptor { return nil } +func (x *CapabilityDescriptor) GetScheduledTask() *ScheduledTaskDescriptor { + if x != nil { + return x.ScheduledTask + } + return nil +} + +// ScheduledTaskDescriptor describes a scheduled_task.v1 capability. +type ScheduledTaskDescriptor struct { + state protoimpl.MessageState `protogen:"open.v1"` + // The schedule the host uses until an administrator sets one. Without it, + // a host runs the task once each time it starts. + DefaultTrigger *ScheduledTaskTrigger `protobuf:"bytes,1,opt,name=default_trigger,json=defaultTrigger,proto3" json:"default_trigger,omitempty"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache +} + +func (x *ScheduledTaskDescriptor) Reset() { + *x = ScheduledTaskDescriptor{} + mi := &file_silo_plugin_v1_common_proto_msgTypes[12] + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + ms.StoreMessageInfo(mi) +} + +func (x *ScheduledTaskDescriptor) String() string { + return protoimpl.X.MessageStringOf(x) +} + +func (*ScheduledTaskDescriptor) ProtoMessage() {} + +func (x *ScheduledTaskDescriptor) ProtoReflect() protoreflect.Message { + mi := &file_silo_plugin_v1_common_proto_msgTypes[12] + 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 ScheduledTaskDescriptor.ProtoReflect.Descriptor instead. +func (*ScheduledTaskDescriptor) Descriptor() ([]byte, []int) { + return file_silo_plugin_v1_common_proto_rawDescGZIP(), []int{12} +} + +func (x *ScheduledTaskDescriptor) GetDefaultTrigger() *ScheduledTaskTrigger { + if x != nil { + return x.DefaultTrigger + } + return nil +} + +// ScheduledTaskTrigger is one schedule for a scheduled task. +type ScheduledTaskTrigger struct { + state protoimpl.MessageState `protogen:"open.v1"` + // "interval", "daily", "weekly" or "startup". The vocabulary is open: a + // host that knows default_trigger uses its own default schedule for a type + // it doesn't know. + Type string `protobuf:"bytes,1,opt,name=type,proto3" json:"type,omitempty"` + // For "interval": milliseconds between runs, at least 60000. + IntervalMs int64 `protobuf:"varint,2,opt,name=interval_ms,json=intervalMs,proto3" json:"interval_ms,omitempty"` + // For "daily" and "weekly": "HH:MM", 24-hour, in the server's local time. + TimeOfDay string `protobuf:"bytes,3,opt,name=time_of_day,json=timeOfDay,proto3" json:"time_of_day,omitempty"` + // For "weekly": 0 (Sunday) to 6 (Saturday). + DayOfWeek int32 `protobuf:"varint,4,opt,name=day_of_week,json=dayOfWeek,proto3" json:"day_of_week,omitempty"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache +} + +func (x *ScheduledTaskTrigger) Reset() { + *x = ScheduledTaskTrigger{} + mi := &file_silo_plugin_v1_common_proto_msgTypes[13] + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + ms.StoreMessageInfo(mi) +} + +func (x *ScheduledTaskTrigger) String() string { + return protoimpl.X.MessageStringOf(x) +} + +func (*ScheduledTaskTrigger) ProtoMessage() {} + +func (x *ScheduledTaskTrigger) ProtoReflect() protoreflect.Message { + mi := &file_silo_plugin_v1_common_proto_msgTypes[13] + 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 ScheduledTaskTrigger.ProtoReflect.Descriptor instead. +func (*ScheduledTaskTrigger) Descriptor() ([]byte, []int) { + return file_silo_plugin_v1_common_proto_rawDescGZIP(), []int{13} +} + +func (x *ScheduledTaskTrigger) GetType() string { + if x != nil { + return x.Type + } + return "" +} + +func (x *ScheduledTaskTrigger) GetIntervalMs() int64 { + if x != nil { + return x.IntervalMs + } + return 0 +} + +func (x *ScheduledTaskTrigger) GetTimeOfDay() string { + if x != nil { + return x.TimeOfDay + } + return "" +} + +func (x *ScheduledTaskTrigger) GetDayOfWeek() int32 { + if x != nil { + return x.DayOfWeek + } + return 0 +} + // PluginPresentation describes a plugin for server operators and links them to // its publisher, source, support, and release history. These values are // self-declared by the plugin and never determine catalog approval. @@ -1128,7 +1264,7 @@ type PluginPresentation struct { func (x *PluginPresentation) Reset() { *x = PluginPresentation{} - mi := &file_silo_plugin_v1_common_proto_msgTypes[12] + mi := &file_silo_plugin_v1_common_proto_msgTypes[14] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -1140,7 +1276,7 @@ func (x *PluginPresentation) String() string { func (*PluginPresentation) ProtoMessage() {} func (x *PluginPresentation) ProtoReflect() protoreflect.Message { - mi := &file_silo_plugin_v1_common_proto_msgTypes[12] + mi := &file_silo_plugin_v1_common_proto_msgTypes[14] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -1153,7 +1289,7 @@ func (x *PluginPresentation) ProtoReflect() protoreflect.Message { // Deprecated: Use PluginPresentation.ProtoReflect.Descriptor instead. func (*PluginPresentation) Descriptor() ([]byte, []int) { - return file_silo_plugin_v1_common_proto_rawDescGZIP(), []int{12} + return file_silo_plugin_v1_common_proto_rawDescGZIP(), []int{14} } func (x *PluginPresentation) GetDisplayName() string { @@ -1269,7 +1405,7 @@ type PluginManifest struct { func (x *PluginManifest) Reset() { *x = PluginManifest{} - mi := &file_silo_plugin_v1_common_proto_msgTypes[13] + mi := &file_silo_plugin_v1_common_proto_msgTypes[15] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -1281,7 +1417,7 @@ func (x *PluginManifest) String() string { func (*PluginManifest) ProtoMessage() {} func (x *PluginManifest) ProtoReflect() protoreflect.Message { - mi := &file_silo_plugin_v1_common_proto_msgTypes[13] + mi := &file_silo_plugin_v1_common_proto_msgTypes[15] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -1294,7 +1430,7 @@ func (x *PluginManifest) ProtoReflect() protoreflect.Message { // Deprecated: Use PluginManifest.ProtoReflect.Descriptor instead. func (*PluginManifest) Descriptor() ([]byte, []int) { - return file_silo_plugin_v1_common_proto_rawDescGZIP(), []int{13} + return file_silo_plugin_v1_common_proto_rawDescGZIP(), []int{15} } func (x *PluginManifest) GetPluginId() string { @@ -1403,7 +1539,7 @@ type GetManifestRequest struct { func (x *GetManifestRequest) Reset() { *x = GetManifestRequest{} - mi := &file_silo_plugin_v1_common_proto_msgTypes[14] + mi := &file_silo_plugin_v1_common_proto_msgTypes[16] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -1415,7 +1551,7 @@ func (x *GetManifestRequest) String() string { func (*GetManifestRequest) ProtoMessage() {} func (x *GetManifestRequest) ProtoReflect() protoreflect.Message { - mi := &file_silo_plugin_v1_common_proto_msgTypes[14] + mi := &file_silo_plugin_v1_common_proto_msgTypes[16] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -1428,7 +1564,7 @@ func (x *GetManifestRequest) ProtoReflect() protoreflect.Message { // Deprecated: Use GetManifestRequest.ProtoReflect.Descriptor instead. func (*GetManifestRequest) Descriptor() ([]byte, []int) { - return file_silo_plugin_v1_common_proto_rawDescGZIP(), []int{14} + return file_silo_plugin_v1_common_proto_rawDescGZIP(), []int{16} } type GetManifestResponse struct { @@ -1440,7 +1576,7 @@ type GetManifestResponse struct { func (x *GetManifestResponse) Reset() { *x = GetManifestResponse{} - mi := &file_silo_plugin_v1_common_proto_msgTypes[15] + mi := &file_silo_plugin_v1_common_proto_msgTypes[17] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -1452,7 +1588,7 @@ func (x *GetManifestResponse) String() string { func (*GetManifestResponse) ProtoMessage() {} func (x *GetManifestResponse) ProtoReflect() protoreflect.Message { - mi := &file_silo_plugin_v1_common_proto_msgTypes[15] + mi := &file_silo_plugin_v1_common_proto_msgTypes[17] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -1465,7 +1601,7 @@ func (x *GetManifestResponse) ProtoReflect() protoreflect.Message { // Deprecated: Use GetManifestResponse.ProtoReflect.Descriptor instead. func (*GetManifestResponse) Descriptor() ([]byte, []int) { - return file_silo_plugin_v1_common_proto_rawDescGZIP(), []int{15} + return file_silo_plugin_v1_common_proto_rawDescGZIP(), []int{17} } func (x *GetManifestResponse) GetManifest() *PluginManifest { @@ -1484,7 +1620,7 @@ type ConfigureRequest struct { func (x *ConfigureRequest) Reset() { *x = ConfigureRequest{} - mi := &file_silo_plugin_v1_common_proto_msgTypes[16] + mi := &file_silo_plugin_v1_common_proto_msgTypes[18] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -1496,7 +1632,7 @@ func (x *ConfigureRequest) String() string { func (*ConfigureRequest) ProtoMessage() {} func (x *ConfigureRequest) ProtoReflect() protoreflect.Message { - mi := &file_silo_plugin_v1_common_proto_msgTypes[16] + mi := &file_silo_plugin_v1_common_proto_msgTypes[18] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -1509,7 +1645,7 @@ func (x *ConfigureRequest) ProtoReflect() protoreflect.Message { // Deprecated: Use ConfigureRequest.ProtoReflect.Descriptor instead. func (*ConfigureRequest) Descriptor() ([]byte, []int) { - return file_silo_plugin_v1_common_proto_rawDescGZIP(), []int{16} + return file_silo_plugin_v1_common_proto_rawDescGZIP(), []int{18} } func (x *ConfigureRequest) GetConfig() []*ConfigEntry { @@ -1527,7 +1663,7 @@ type ConfigureResponse struct { func (x *ConfigureResponse) Reset() { *x = ConfigureResponse{} - mi := &file_silo_plugin_v1_common_proto_msgTypes[17] + mi := &file_silo_plugin_v1_common_proto_msgTypes[19] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -1539,7 +1675,7 @@ func (x *ConfigureResponse) String() string { func (*ConfigureResponse) ProtoMessage() {} func (x *ConfigureResponse) ProtoReflect() protoreflect.Message { - mi := &file_silo_plugin_v1_common_proto_msgTypes[17] + mi := &file_silo_plugin_v1_common_proto_msgTypes[19] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -1552,7 +1688,7 @@ func (x *ConfigureResponse) ProtoReflect() protoreflect.Message { // Deprecated: Use ConfigureResponse.ProtoReflect.Descriptor instead. func (*ConfigureResponse) Descriptor() ([]byte, []int) { - return file_silo_plugin_v1_common_proto_rawDescGZIP(), []int{17} + return file_silo_plugin_v1_common_proto_rawDescGZIP(), []int{19} } type BindHostBrokerRequest struct { @@ -1564,7 +1700,7 @@ type BindHostBrokerRequest struct { func (x *BindHostBrokerRequest) Reset() { *x = BindHostBrokerRequest{} - mi := &file_silo_plugin_v1_common_proto_msgTypes[18] + mi := &file_silo_plugin_v1_common_proto_msgTypes[20] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -1576,7 +1712,7 @@ func (x *BindHostBrokerRequest) String() string { func (*BindHostBrokerRequest) ProtoMessage() {} func (x *BindHostBrokerRequest) ProtoReflect() protoreflect.Message { - mi := &file_silo_plugin_v1_common_proto_msgTypes[18] + mi := &file_silo_plugin_v1_common_proto_msgTypes[20] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -1589,7 +1725,7 @@ func (x *BindHostBrokerRequest) ProtoReflect() protoreflect.Message { // Deprecated: Use BindHostBrokerRequest.ProtoReflect.Descriptor instead. func (*BindHostBrokerRequest) Descriptor() ([]byte, []int) { - return file_silo_plugin_v1_common_proto_rawDescGZIP(), []int{18} + return file_silo_plugin_v1_common_proto_rawDescGZIP(), []int{20} } func (x *BindHostBrokerRequest) GetBrokerId() uint32 { @@ -1607,7 +1743,7 @@ type BindHostBrokerResponse struct { func (x *BindHostBrokerResponse) Reset() { *x = BindHostBrokerResponse{} - mi := &file_silo_plugin_v1_common_proto_msgTypes[19] + mi := &file_silo_plugin_v1_common_proto_msgTypes[21] ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) ms.StoreMessageInfo(mi) } @@ -1619,7 +1755,7 @@ func (x *BindHostBrokerResponse) String() string { func (*BindHostBrokerResponse) ProtoMessage() {} func (x *BindHostBrokerResponse) ProtoReflect() protoreflect.Message { - mi := &file_silo_plugin_v1_common_proto_msgTypes[19] + mi := &file_silo_plugin_v1_common_proto_msgTypes[21] if x != nil { ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) if ms.LoadMessageInfo() == nil { @@ -1632,7 +1768,7 @@ func (x *BindHostBrokerResponse) ProtoReflect() protoreflect.Message { // Deprecated: Use BindHostBrokerResponse.ProtoReflect.Descriptor instead. func (*BindHostBrokerResponse) Descriptor() ([]byte, []int) { - return file_silo_plugin_v1_common_proto_rawDescGZIP(), []int{19} + return file_silo_plugin_v1_common_proto_rawDescGZIP(), []int{21} } var File_silo_plugin_v1_common_proto protoreflect.FileDescriptor @@ -1716,7 +1852,7 @@ const file_silo_plugin_v1_common_proto_rawDesc = "" + "\rPackagedAsset\x12\x12\n" + "\x04path\x18\x01 \x01(\tR\x04path\x12!\n" + "\fcontent_type\x18\x02 \x01(\tR\vcontentType\x12\x1c\n" + - "\tintegrity\x18\x03 \x01(\tR\tintegrity\"\xed\x04\n" + + "\tintegrity\x18\x03 \x01(\tR\tintegrity\"\xbd\x05\n" + "\x14CapabilityDescriptor\x12\x12\n" + "\x04type\x18\x01 \x01(\tR\x04type\x12\x0e\n" + "\x02id\x18\x02 \x01(\tR\x02id\x12!\n" + @@ -1731,7 +1867,16 @@ const file_silo_plugin_v1_common_proto_rawDesc = "" + "\x13watch_sync_provider\x18\n" + " \x01(\v2+.silo.plugin.v1.WatchSyncProviderDescriptorR\x11watchSyncProvider\x12g\n" + "\x17network_access_provider\x18\v \x01(\v2/.silo.plugin.v1.NetworkAccessProviderDescriptorR\x15networkAccessProvider\x12N\n" + - "\x0erequest_router\x18\f \x01(\v2'.silo.plugin.v1.RequestRouterDescriptorR\rrequestRouter\"\xa2\x03\n" + + "\x0erequest_router\x18\f \x01(\v2'.silo.plugin.v1.RequestRouterDescriptorR\rrequestRouter\x12N\n" + + "\x0escheduled_task\x18\x0e \x01(\v2'.silo.plugin.v1.ScheduledTaskDescriptorR\rscheduledTask\"h\n" + + "\x17ScheduledTaskDescriptor\x12M\n" + + "\x0fdefault_trigger\x18\x01 \x01(\v2$.silo.plugin.v1.ScheduledTaskTriggerR\x0edefaultTrigger\"\x8b\x01\n" + + "\x14ScheduledTaskTrigger\x12\x12\n" + + "\x04type\x18\x01 \x01(\tR\x04type\x12\x1f\n" + + "\vinterval_ms\x18\x02 \x01(\x03R\n" + + "intervalMs\x12\x1e\n" + + "\vtime_of_day\x18\x03 \x01(\tR\ttimeOfDay\x12\x1e\n" + + "\vday_of_week\x18\x04 \x01(\x05R\tdayOfWeek\"\xa2\x03\n" + "\x12PluginPresentation\x12!\n" + "\fdisplay_name\x18\x01 \x01(\tR\vdisplayName\x12\x18\n" + "\asummary\x18\x02 \x01(\tR\asummary\x121\n" + @@ -1800,7 +1945,7 @@ func file_silo_plugin_v1_common_proto_rawDescGZIP() []byte { } var file_silo_plugin_v1_common_proto_enumTypes = make([]protoimpl.EnumInfo, 1) -var file_silo_plugin_v1_common_proto_msgTypes = make([]protoimpl.MessageInfo, 20) +var file_silo_plugin_v1_common_proto_msgTypes = make([]protoimpl.MessageInfo, 22) var file_silo_plugin_v1_common_proto_goTypes = []any{ (AdminFormControl)(0), // 0: silo.plugin.v1.AdminFormControl (*SupportedPlatform)(nil), // 1: silo.plugin.v1.SupportedPlatform @@ -1815,57 +1960,61 @@ var file_silo_plugin_v1_common_proto_goTypes = []any{ (*HttpRouteDescriptor)(nil), // 10: silo.plugin.v1.HttpRouteDescriptor (*PackagedAsset)(nil), // 11: silo.plugin.v1.PackagedAsset (*CapabilityDescriptor)(nil), // 12: silo.plugin.v1.CapabilityDescriptor - (*PluginPresentation)(nil), // 13: silo.plugin.v1.PluginPresentation - (*PluginManifest)(nil), // 14: silo.plugin.v1.PluginManifest - (*GetManifestRequest)(nil), // 15: silo.plugin.v1.GetManifestRequest - (*GetManifestResponse)(nil), // 16: silo.plugin.v1.GetManifestResponse - (*ConfigureRequest)(nil), // 17: silo.plugin.v1.ConfigureRequest - (*ConfigureResponse)(nil), // 18: silo.plugin.v1.ConfigureResponse - (*BindHostBrokerRequest)(nil), // 19: silo.plugin.v1.BindHostBrokerRequest - (*BindHostBrokerResponse)(nil), // 20: silo.plugin.v1.BindHostBrokerResponse - (*structpb.Value)(nil), // 21: google.protobuf.Value - (*structpb.Struct)(nil), // 22: google.protobuf.Struct - (*WatchSyncProviderDescriptor)(nil), // 23: silo.plugin.v1.WatchSyncProviderDescriptor - (*NetworkAccessProviderDescriptor)(nil), // 24: silo.plugin.v1.NetworkAccessProviderDescriptor - (*RequestRouterDescriptor)(nil), // 25: silo.plugin.v1.RequestRouterDescriptor + (*ScheduledTaskDescriptor)(nil), // 13: silo.plugin.v1.ScheduledTaskDescriptor + (*ScheduledTaskTrigger)(nil), // 14: silo.plugin.v1.ScheduledTaskTrigger + (*PluginPresentation)(nil), // 15: silo.plugin.v1.PluginPresentation + (*PluginManifest)(nil), // 16: silo.plugin.v1.PluginManifest + (*GetManifestRequest)(nil), // 17: silo.plugin.v1.GetManifestRequest + (*GetManifestResponse)(nil), // 18: silo.plugin.v1.GetManifestResponse + (*ConfigureRequest)(nil), // 19: silo.plugin.v1.ConfigureRequest + (*ConfigureResponse)(nil), // 20: silo.plugin.v1.ConfigureResponse + (*BindHostBrokerRequest)(nil), // 21: silo.plugin.v1.BindHostBrokerRequest + (*BindHostBrokerResponse)(nil), // 22: silo.plugin.v1.BindHostBrokerResponse + (*structpb.Value)(nil), // 23: google.protobuf.Value + (*structpb.Struct)(nil), // 24: google.protobuf.Struct + (*WatchSyncProviderDescriptor)(nil), // 25: silo.plugin.v1.WatchSyncProviderDescriptor + (*NetworkAccessProviderDescriptor)(nil), // 26: silo.plugin.v1.NetworkAccessProviderDescriptor + (*RequestRouterDescriptor)(nil), // 27: silo.plugin.v1.RequestRouterDescriptor } var file_silo_plugin_v1_common_proto_depIdxs = []int32{ 8, // 0: silo.plugin.v1.ConfigSchema.admin_form:type_name -> silo.plugin.v1.AdminFormDescriptor 0, // 1: silo.plugin.v1.AdminFormField.control:type_name -> silo.plugin.v1.AdminFormControl - 21, // 2: silo.plugin.v1.AdminFormField.default_value:type_name -> google.protobuf.Value + 23, // 2: silo.plugin.v1.AdminFormField.default_value:type_name -> google.protobuf.Value 3, // 3: silo.plugin.v1.AdminFormField.options:type_name -> silo.plugin.v1.AdminFormOption 5, // 4: silo.plugin.v1.AdminFormField.show_when:type_name -> silo.plugin.v1.AdminFormCondition 6, // 5: silo.plugin.v1.AdminFormField.validation:type_name -> silo.plugin.v1.AdminFormValidation 5, // 6: silo.plugin.v1.AdminFormSection.show_when:type_name -> silo.plugin.v1.AdminFormCondition 4, // 7: silo.plugin.v1.AdminFormDescriptor.fields:type_name -> silo.plugin.v1.AdminFormField 7, // 8: silo.plugin.v1.AdminFormDescriptor.sections:type_name -> silo.plugin.v1.AdminFormSection - 22, // 9: silo.plugin.v1.ConfigEntry.value:type_name -> google.protobuf.Struct + 24, // 9: silo.plugin.v1.ConfigEntry.value:type_name -> google.protobuf.Struct 2, // 10: silo.plugin.v1.CapabilityDescriptor.config_schema:type_name -> silo.plugin.v1.ConfigSchema - 22, // 11: silo.plugin.v1.CapabilityDescriptor.metadata:type_name -> google.protobuf.Struct - 23, // 12: silo.plugin.v1.CapabilityDescriptor.watch_sync_provider:type_name -> silo.plugin.v1.WatchSyncProviderDescriptor - 24, // 13: silo.plugin.v1.CapabilityDescriptor.network_access_provider:type_name -> silo.plugin.v1.NetworkAccessProviderDescriptor - 25, // 14: silo.plugin.v1.CapabilityDescriptor.request_router:type_name -> silo.plugin.v1.RequestRouterDescriptor - 1, // 15: silo.plugin.v1.PluginManifest.supported_platforms:type_name -> silo.plugin.v1.SupportedPlatform - 12, // 16: silo.plugin.v1.PluginManifest.capabilities:type_name -> silo.plugin.v1.CapabilityDescriptor - 2, // 17: silo.plugin.v1.PluginManifest.global_config_schema:type_name -> silo.plugin.v1.ConfigSchema - 2, // 18: silo.plugin.v1.PluginManifest.user_config_schema:type_name -> silo.plugin.v1.ConfigSchema - 10, // 19: silo.plugin.v1.PluginManifest.http_routes:type_name -> silo.plugin.v1.HttpRouteDescriptor - 11, // 20: silo.plugin.v1.PluginManifest.assets:type_name -> silo.plugin.v1.PackagedAsset - 22, // 21: silo.plugin.v1.PluginManifest.metadata:type_name -> google.protobuf.Struct - 13, // 22: silo.plugin.v1.PluginManifest.presentation:type_name -> silo.plugin.v1.PluginPresentation - 14, // 23: silo.plugin.v1.GetManifestResponse.manifest:type_name -> silo.plugin.v1.PluginManifest - 9, // 24: silo.plugin.v1.ConfigureRequest.config:type_name -> silo.plugin.v1.ConfigEntry - 15, // 25: silo.plugin.v1.Runtime.GetManifest:input_type -> silo.plugin.v1.GetManifestRequest - 17, // 26: silo.plugin.v1.Runtime.Configure:input_type -> silo.plugin.v1.ConfigureRequest - 19, // 27: silo.plugin.v1.Runtime.BindHostBroker:input_type -> silo.plugin.v1.BindHostBrokerRequest - 16, // 28: silo.plugin.v1.Runtime.GetManifest:output_type -> silo.plugin.v1.GetManifestResponse - 18, // 29: silo.plugin.v1.Runtime.Configure:output_type -> silo.plugin.v1.ConfigureResponse - 20, // 30: silo.plugin.v1.Runtime.BindHostBroker:output_type -> silo.plugin.v1.BindHostBrokerResponse - 28, // [28:31] is the sub-list for method output_type - 25, // [25:28] is the sub-list for method input_type - 25, // [25:25] is the sub-list for extension type_name - 25, // [25:25] is the sub-list for extension extendee - 0, // [0:25] is the sub-list for field type_name + 24, // 11: silo.plugin.v1.CapabilityDescriptor.metadata:type_name -> google.protobuf.Struct + 25, // 12: silo.plugin.v1.CapabilityDescriptor.watch_sync_provider:type_name -> silo.plugin.v1.WatchSyncProviderDescriptor + 26, // 13: silo.plugin.v1.CapabilityDescriptor.network_access_provider:type_name -> silo.plugin.v1.NetworkAccessProviderDescriptor + 27, // 14: silo.plugin.v1.CapabilityDescriptor.request_router:type_name -> silo.plugin.v1.RequestRouterDescriptor + 13, // 15: silo.plugin.v1.CapabilityDescriptor.scheduled_task:type_name -> silo.plugin.v1.ScheduledTaskDescriptor + 14, // 16: silo.plugin.v1.ScheduledTaskDescriptor.default_trigger:type_name -> silo.plugin.v1.ScheduledTaskTrigger + 1, // 17: silo.plugin.v1.PluginManifest.supported_platforms:type_name -> silo.plugin.v1.SupportedPlatform + 12, // 18: silo.plugin.v1.PluginManifest.capabilities:type_name -> silo.plugin.v1.CapabilityDescriptor + 2, // 19: silo.plugin.v1.PluginManifest.global_config_schema:type_name -> silo.plugin.v1.ConfigSchema + 2, // 20: silo.plugin.v1.PluginManifest.user_config_schema:type_name -> silo.plugin.v1.ConfigSchema + 10, // 21: silo.plugin.v1.PluginManifest.http_routes:type_name -> silo.plugin.v1.HttpRouteDescriptor + 11, // 22: silo.plugin.v1.PluginManifest.assets:type_name -> silo.plugin.v1.PackagedAsset + 24, // 23: silo.plugin.v1.PluginManifest.metadata:type_name -> google.protobuf.Struct + 15, // 24: silo.plugin.v1.PluginManifest.presentation:type_name -> silo.plugin.v1.PluginPresentation + 16, // 25: silo.plugin.v1.GetManifestResponse.manifest:type_name -> silo.plugin.v1.PluginManifest + 9, // 26: silo.plugin.v1.ConfigureRequest.config:type_name -> silo.plugin.v1.ConfigEntry + 17, // 27: silo.plugin.v1.Runtime.GetManifest:input_type -> silo.plugin.v1.GetManifestRequest + 19, // 28: silo.plugin.v1.Runtime.Configure:input_type -> silo.plugin.v1.ConfigureRequest + 21, // 29: silo.plugin.v1.Runtime.BindHostBroker:input_type -> silo.plugin.v1.BindHostBrokerRequest + 18, // 30: silo.plugin.v1.Runtime.GetManifest:output_type -> silo.plugin.v1.GetManifestResponse + 20, // 31: silo.plugin.v1.Runtime.Configure:output_type -> silo.plugin.v1.ConfigureResponse + 22, // 32: silo.plugin.v1.Runtime.BindHostBroker:output_type -> silo.plugin.v1.BindHostBrokerResponse + 30, // [30:33] is the sub-list for method output_type + 27, // [27:30] is the sub-list for method input_type + 27, // [27:27] is the sub-list for extension type_name + 27, // [27:27] is the sub-list for extension extendee + 0, // [0:27] is the sub-list for field type_name } func init() { file_silo_plugin_v1_common_proto_init() } @@ -1882,7 +2031,7 @@ func file_silo_plugin_v1_common_proto_init() { GoPackagePath: reflect.TypeOf(x{}).PkgPath(), RawDescriptor: unsafe.Slice(unsafe.StringData(file_silo_plugin_v1_common_proto_rawDesc), len(file_silo_plugin_v1_common_proto_rawDesc)), NumEnums: 1, - NumMessages: 20, + NumMessages: 22, NumExtensions: 0, NumServices: 1, }, diff --git a/pkg/pluginsdk/convert/convert.go b/pkg/pluginsdk/convert/convert.go index 93c324c..9f52bf9 100644 --- a/pkg/pluginsdk/convert/convert.go +++ b/pkg/pluginsdk/convert/convert.go @@ -92,6 +92,17 @@ func DecodeCapability(record CapabilityRecord) (*pluginv1.CapabilityDescriptor, } descriptor.RequestRouter = &typed } + if task, ok := record.Metadata["scheduled_task"]; ok { + data, err := json.Marshal(task) + if err != nil { + return nil, fmt.Errorf("encode scheduled task descriptor: %w", err) + } + var typed pluginv1.ScheduledTaskDescriptor + if err := capabilityUnmarshal.Unmarshal(data, &typed); err != nil { + return nil, fmt.Errorf("decode scheduled task descriptor: %w", err) + } + descriptor.ScheduledTask = &typed + } if configSchema, ok := record.Metadata["config_schema"]; ok { schemas, err := decodeConfigSchemas(configSchema) if err != nil { @@ -150,6 +161,17 @@ func capabilityMetadata(descriptor *pluginv1.CapabilityDescriptor) (map[string]a } metadata["request_router"] = value } + if descriptor.GetScheduledTask() != nil { + data, err := protojson.MarshalOptions{UseProtoNames: true}.Marshal(descriptor.GetScheduledTask()) + if err != nil { + return nil, fmt.Errorf("encode scheduled task descriptor: %w", err) + } + var value map[string]any + if err := json.Unmarshal(data, &value); err != nil { + return nil, fmt.Errorf("decode scheduled task descriptor JSON: %w", err) + } + metadata["scheduled_task"] = value + } if len(descriptor.GetConfigSchema()) > 0 { schemas := make([]map[string]any, 0, len(descriptor.GetConfigSchema())) for _, schema := range descriptor.GetConfigSchema() { diff --git a/pkg/pluginsdk/convert/scheduled_task_test.go b/pkg/pluginsdk/convert/scheduled_task_test.go new file mode 100644 index 0000000..2d5dda3 --- /dev/null +++ b/pkg/pluginsdk/convert/scheduled_task_test.go @@ -0,0 +1,35 @@ +package convert_test + +import ( + "testing" + + "google.golang.org/protobuf/proto" + + pluginv1 "github.com/Silo-Server/silo-plugin-sdk/pkg/pluginproto/silo/plugin/v1" + "github.com/Silo-Server/silo-plugin-sdk/pkg/pluginsdk/convert" +) + +// The host reads a task's default schedule from its stored capability +// record, so the descriptor must survive the round trip, including on a node +// whose SDK predates fields a newer one stored. +func TestScheduledTaskDescriptorRoundTrip(t *testing.T) { + descriptor := &pluginv1.ScheduledTaskDescriptor{DefaultTrigger: &pluginv1.ScheduledTaskTrigger{ + Type: "weekly", TimeOfDay: "18:00", DayOfWeek: 6, + }} + records, err := convert.CapabilityRecordsFromManifest(&pluginv1.PluginManifest{Capabilities: []*pluginv1.CapabilityDescriptor{{ + Type: "scheduled_task.v1", Id: "digest", ScheduledTask: descriptor, + }}}) + if err != nil { + t.Fatal(err) + } + stored := records[0].Metadata["scheduled_task"].(map[string]any) + stored["future_field"] = true + stored["default_trigger"].(map[string]any)["future_option"] = "x" + decoded, err := convert.DecodeCapability(records[0]) + if err != nil { + t.Fatal(err) + } + if !proto.Equal(decoded.GetScheduledTask(), descriptor) { + t.Fatalf("decoded descriptor = %v, want %v", decoded.GetScheduledTask(), descriptor) + } +} diff --git a/pkg/pluginsdk/manifest/manifest.go b/pkg/pluginsdk/manifest/manifest.go index 5d7291c..a241051 100644 --- a/pkg/pluginsdk/manifest/manifest.go +++ b/pkg/pluginsdk/manifest/manifest.go @@ -153,6 +153,9 @@ func Validate(manifest *pluginv1.PluginManifest) error { if err := validateAuthProviderCapability(capability); err != nil { return err } + if err := validateScheduledTaskCapability(capability); err != nil { + return err + } } if err := validateNetworkAuthPairing(manifest); err != nil { return err diff --git a/pkg/pluginsdk/manifest/scheduled_task.go b/pkg/pluginsdk/manifest/scheduled_task.go new file mode 100644 index 0000000..20503fd --- /dev/null +++ b/pkg/pluginsdk/manifest/scheduled_task.go @@ -0,0 +1,67 @@ +package manifest + +import ( + "fmt" + "regexp" + + pluginv1 "github.com/Silo-Server/silo-plugin-sdk/pkg/pluginproto/silo/plugin/v1" + "github.com/Silo-Server/silo-plugin-sdk/pkg/pluginsdk/capability" +) + +var ( + timeOfDayPattern = regexp.MustCompile(`^([01][0-9]|2[0-3]):[0-5][0-9]$`) +) + +// Scheduled task trigger types this SDK knows. The vocabulary is open: a +// host falls back to its default schedule for a type it doesn't know. +const ( + TriggerTypeInterval = "interval" + TriggerTypeDaily = "daily" + TriggerTypeWeekly = "weekly" + TriggerTypeStartup = "startup" + + // MinTriggerIntervalMs is the shortest default interval a manifest may + // declare. + MinTriggerIntervalMs = 60_000 + // MaxTriggerIntervalMs is the longest interval a host timer holds + // (about 292 years); a longer one overflows. + MaxTriggerIntervalMs = 9_223_372_036_854 +) + +func validateScheduledTaskCapability(descriptor *pluginv1.CapabilityDescriptor) error { + task := descriptor.GetScheduledTask() + if task == nil { + return nil + } + if descriptor.GetType() != capability.ScheduledTask { + return fmt.Errorf("plugin capability %q: scheduled_task descriptor requires type %q", descriptor.GetId(), capability.ScheduledTask) + } + trigger := task.GetDefaultTrigger() + if trigger == nil { + return nil + } + invalid := func(format string, args ...any) error { + return fmt.Errorf("plugin capability %q default_trigger: "+format, append([]any{descriptor.GetId()}, args...)...) + } + switch trigger.GetType() { + case "": + return invalid("type is required") + case TriggerTypeInterval: + if trigger.GetIntervalMs() < MinTriggerIntervalMs { + return invalid("interval_ms must be at least %d", MinTriggerIntervalMs) + } + if trigger.GetIntervalMs() > MaxTriggerIntervalMs { + return invalid("interval_ms must be at most %d", MaxTriggerIntervalMs) + } + case TriggerTypeWeekly: + if day := trigger.GetDayOfWeek(); day < 0 || day > 6 { + return invalid("day_of_week must be 0 (Sunday) to 6 (Saturday)") + } + fallthrough + case TriggerTypeDaily: + if !timeOfDayPattern.MatchString(trigger.GetTimeOfDay()) { + return invalid("time_of_day must be HH:MM") + } + } + return nil +} diff --git a/pkg/pluginsdk/manifest/scheduled_task_test.go b/pkg/pluginsdk/manifest/scheduled_task_test.go new file mode 100644 index 0000000..17cf943 --- /dev/null +++ b/pkg/pluginsdk/manifest/scheduled_task_test.go @@ -0,0 +1,48 @@ +package manifest_test + +import ( + "strings" + "testing" + + pluginv1 "github.com/Silo-Server/silo-plugin-sdk/pkg/pluginproto/silo/plugin/v1" + publicmanifest "github.com/Silo-Server/silo-plugin-sdk/pkg/pluginsdk/manifest" +) + +func TestValidateScheduledTaskDefaultTrigger(t *testing.T) { + for _, tc := range []struct { + name string + typ string + trigger *pluginv1.ScheduledTaskTrigger + wantErr string + }{ + {name: "interval", typ: "scheduled_task.v1", trigger: &pluginv1.ScheduledTaskTrigger{Type: "interval", IntervalMs: 300_000}}, + {name: "daily", typ: "scheduled_task.v1", trigger: &pluginv1.ScheduledTaskTrigger{Type: "daily", TimeOfDay: "03:30"}}, + {name: "weekly", typ: "scheduled_task.v1", trigger: &pluginv1.ScheduledTaskTrigger{Type: "weekly", TimeOfDay: "18:00", DayOfWeek: 0}}, + {name: "startup", typ: "scheduled_task.v1", trigger: &pluginv1.ScheduledTaskTrigger{Type: "startup"}}, + // A newer SDK's trigger type passes validation; a host that knows + // default_trigger but not the type uses its own default. + {name: "type this SDK doesn't know", typ: "scheduled_task.v1", trigger: &pluginv1.ScheduledTaskTrigger{Type: "cron"}}, + {name: "no type", typ: "scheduled_task.v1", trigger: &pluginv1.ScheduledTaskTrigger{IntervalMs: 300_000}, wantErr: "type is required"}, + {name: "interval too short", typ: "scheduled_task.v1", trigger: &pluginv1.ScheduledTaskTrigger{Type: "interval", IntervalMs: 5_000}, wantErr: "interval_ms"}, + {name: "interval too long for a timer", typ: "scheduled_task.v1", trigger: &pluginv1.ScheduledTaskTrigger{Type: "interval", IntervalMs: 9_223_372_036_855}, wantErr: "interval_ms"}, + {name: "daily without time", typ: "scheduled_task.v1", trigger: &pluginv1.ScheduledTaskTrigger{Type: "daily"}, wantErr: "time_of_day"}, + {name: "daily at 24:00", typ: "scheduled_task.v1", trigger: &pluginv1.ScheduledTaskTrigger{Type: "daily", TimeOfDay: "24:00"}, wantErr: "time_of_day"}, + {name: "weekly on day 7", typ: "scheduled_task.v1", trigger: &pluginv1.ScheduledTaskTrigger{Type: "weekly", TimeOfDay: "18:00", DayOfWeek: 7}, wantErr: "day_of_week"}, + {name: "descriptor on another type", typ: "event_consumer.v1", trigger: &pluginv1.ScheduledTaskTrigger{Type: "startup"}, wantErr: "requires type"}, + } { + t.Run(tc.name, func(t *testing.T) { + err := publicmanifest.Validate(&pluginv1.PluginManifest{PluginId: "silo.test", Version: "1.0.0", + Capabilities: []*pluginv1.CapabilityDescriptor{{Type: tc.typ, Id: "task", + ScheduledTask: &pluginv1.ScheduledTaskDescriptor{DefaultTrigger: tc.trigger}}}}) + if tc.wantErr == "" { + if err != nil { + t.Fatalf("Validate() = %v, want nil", err) + } + return + } + if err == nil || !strings.Contains(err.Error(), tc.wantErr) { + t.Fatalf("Validate() = %v, want error containing %q", err, tc.wantErr) + } + }) + } +} diff --git a/proto/silo/plugin/v1/common.proto b/proto/silo/plugin/v1/common.proto index 6c94242..66f7626 100644 --- a/proto/silo/plugin/v1/common.proto +++ b/proto/silo/plugin/v1/common.proto @@ -157,6 +157,35 @@ message CapabilityDescriptor { // of type "request_router.v1". Optional: an absent descriptor declares no // optional request-router features. RequestRouterDescriptor request_router = 12; + + // Typed scheduled-task metadata. Optional, and only meaningful on + // capabilities of type "scheduled_task.v1". A host that predates the field + // ignores it only if it drops unknown fields wherever it reads the + // manifest. Silo hosts built before Silo-Server/silo-server#2502 don't, and + // refuse to install or start a plugin that sets it (see + // docs/scheduled-task.md). + ScheduledTaskDescriptor scheduled_task = 14; +} + +// ScheduledTaskDescriptor describes a scheduled_task.v1 capability. +message ScheduledTaskDescriptor { + // The schedule the host uses until an administrator sets one. Without it, + // a host runs the task once each time it starts. + ScheduledTaskTrigger default_trigger = 1; +} + +// ScheduledTaskTrigger is one schedule for a scheduled task. +message ScheduledTaskTrigger { + // "interval", "daily", "weekly" or "startup". The vocabulary is open: a + // host that knows default_trigger uses its own default schedule for a type + // it doesn't know. + string type = 1; + // For "interval": milliseconds between runs, at least 60000. + int64 interval_ms = 2; + // For "daily" and "weekly": "HH:MM", 24-hour, in the server's local time. + string time_of_day = 3; + // For "weekly": 0 (Sunday) to 6 (Saturday). + int32 day_of_week = 4; } // PluginPresentation describes a plugin for server operators and links them to