From fee6f26ddfbc822c83d75e27d92338f1264f194b Mon Sep 17 00:00:00 2001 From: Maik Groten Date: Wed, 11 Nov 2026 21:06:12 +0100 Subject: [PATCH 1/2] feat(admin-form): let sections be the slots of a list the admin grows An admin form is a fixed set of fields, so a plugin whose settings are a list, such as several named groups of folders, had to show every entry it could ever hold as its own section. AdminFormSection.add_group marks a section as one slot of a list, and add_label is the text of the button that reveals the next slot. A host shows the first slot, every slot up to the last one that holds a value other than its fields' defaults, and the button while a slot is left. The admin can also change the order of the slots: two slots trade the values of their fields at the same position in field_keys, so every slot of a list declares the same fields in the same order. The slots' fields stay ordinary config keys, so what a plugin reads does not change, and the list is as long as the sections it declares. Manifest validation requires add_label with add_group. Hosts that predate the fields drop them and show every slot as a section. AI disclosure: written with Claude Fable 5.2 in Claude Code. go test ./... and go vet pass locally. Co-Authored-By: Claude Fable 5.2 --- docs/compatibility.md | 10 +++++ pkg/pluginproto/silo/plugin/v1/common.pb.go | 38 +++++++++++++++-- .../manifest/admin_form_rich_test.go | 42 +++++++++++++++++++ pkg/pluginsdk/manifest/manifest.go | 13 ++++++ proto/silo/plugin/v1/common.proto | 14 +++++++ 5 files changed, 113 insertions(+), 4 deletions(-) diff --git a/docs/compatibility.md b/docs/compatibility.md index 1460788..6f8830c 100644 --- a/docs/compatibility.md +++ b/docs/compatibility.md @@ -198,6 +198,16 @@ Hosts read the field from the capability metadata stored when the plugin was installed or updated, so it takes effect after the plugin is next updated on a host that reads it. +`AdminFormSection.add_group` and `add_label` turn sections into the slots of a +list the admin grows with a button. Empty means an ordinary section, which is +the behaviour hosts had before the fields existed. Hosts that predate them drop +them as unknown fields when they install a plugin archive, and show every slot +as its own section, so the form still works there. Silo reads a bare plugin +binary's manifest strictly, so a Silo host that predates the fields refuses to +install a binary that declares them; install it from an archive there. The +slots' fields are ordinary config keys, so nothing changes in what the plugin +reads. + `MetadataItem.overview_language` and the `title_language` and `overview_language` fields on `SeasonRecord` and `EpisodeRecord` (added in v0.29.0) are plain strings, like the older `MetadataItem.title_language`. diff --git a/pkg/pluginproto/silo/plugin/v1/common.pb.go b/pkg/pluginproto/silo/plugin/v1/common.pb.go index f220d5c..78d0297 100644 --- a/pkg/pluginproto/silo/plugin/v1/common.pb.go +++ b/pkg/pluginproto/silo/plugin/v1/common.pb.go @@ -600,8 +600,22 @@ type AdminFormSection struct { CollapsedDefault bool `protobuf:"varint,5,opt,name=collapsed_default,json=collapsedDefault,proto3" json:"collapsed_default,omitempty"` FieldKeys []string `protobuf:"bytes,6,rep,name=field_keys,json=fieldKeys,proto3" json:"field_keys,omitempty"` ShowWhen []*AdminFormCondition `protobuf:"bytes,7,rep,name=show_when,json=showWhen,proto3" json:"show_when,omitempty"` - unknownFields protoimpl.UnknownFields - sizeCache protoimpl.SizeCache + // add_group makes the section one slot of a list the admin grows. Sections + // with the same add_group are its slots, in form order. The form shows the + // first slot and every slot up to the last one that holds a value other + // than its fields' defaults, then a button that reveals the next slot. The + // slots' fields are ordinary config keys, so the list is as long as the + // sections the plugin declares. The admin can also change the order of the + // slots: two slots trade places by trading the values of their fields at + // the same position in field_keys, so every slot of a list declares the + // same fields in the same order. A slot whose first field is a text field + // shows that value in its header. Empty = an ordinary section. + AddGroup string `protobuf:"bytes,8,opt,name=add_group,json=addGroup,proto3" json:"add_group,omitempty"` + // add_label is the text of that button, such as "Add storage group". + // Required when add_group is set. + AddLabel string `protobuf:"bytes,9,opt,name=add_label,json=addLabel,proto3" json:"add_label,omitempty"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache } func (x *AdminFormSection) Reset() { @@ -683,6 +697,20 @@ func (x *AdminFormSection) GetShowWhen() []*AdminFormCondition { return nil } +func (x *AdminFormSection) GetAddGroup() string { + if x != nil { + return x.AddGroup + } + return "" +} + +func (x *AdminFormSection) GetAddLabel() string { + if x != nil { + return x.AddLabel + } + return "" +} + type AdminFormDescriptor struct { state protoimpl.MessageState `protogen:"open.v1"` Fields []*AdminFormField `protobuf:"bytes,1,rep,name=fields,proto3" json:"fields,omitempty"` @@ -1672,7 +1700,7 @@ const file_silo_plugin_v1_common_proto_rawDesc = "" + "\n" + "min_length\x18\x06 \x01(\x05R\tminLength\x12\x1d\n" + "\n" + - "max_length\x18\a \x01(\x05R\tmaxLength\"\x8b\x02\n" + + "max_length\x18\a \x01(\x05R\tmaxLength\"\xc5\x02\n" + "\x10AdminFormSection\x12\x10\n" + "\x03key\x18\x01 \x01(\tR\x03key\x12\x14\n" + "\x05title\x18\x02 \x01(\tR\x05title\x12 \n" + @@ -1681,7 +1709,9 @@ const file_silo_plugin_v1_common_proto_rawDesc = "" + "\x11collapsed_default\x18\x05 \x01(\bR\x10collapsedDefault\x12\x1d\n" + "\n" + "field_keys\x18\x06 \x03(\tR\tfieldKeys\x12?\n" + - "\tshow_when\x18\a \x03(\v2\".silo.plugin.v1.AdminFormConditionR\bshowWhen\"\xae\x01\n" + + "\tshow_when\x18\a \x03(\v2\".silo.plugin.v1.AdminFormConditionR\bshowWhen\x12\x1b\n" + + "\tadd_group\x18\b \x01(\tR\baddGroup\x12\x1b\n" + + "\tadd_label\x18\t \x01(\tR\baddLabel\"\xae\x01\n" + "\x13AdminFormDescriptor\x126\n" + "\x06fields\x18\x01 \x03(\v2\x1e.silo.plugin.v1.AdminFormFieldR\x06fields\x12!\n" + "\fsubmit_label\x18\x02 \x01(\tR\vsubmitLabel\x12<\n" + diff --git a/pkg/pluginsdk/manifest/admin_form_rich_test.go b/pkg/pluginsdk/manifest/admin_form_rich_test.go index 245eba0..0ae4263 100644 --- a/pkg/pluginsdk/manifest/admin_form_rich_test.go +++ b/pkg/pluginsdk/manifest/admin_form_rich_test.go @@ -322,3 +322,45 @@ func TestForwardReferenceShowWhenPassesValidation(t *testing.T) { t.Fatalf("Load rejected valid rich admin form with forward-referencing show_when: %v", err) } } + +// TestSectionAddGroup checks the sections of a list the admin grows: a slot +// needs the label of the button that reveals the next one, and a label needs +// a list. +func TestSectionAddGroup(t *testing.T) { + load := func(sections string) error { + _, err := manifest.Load([]byte(`{ + "plugin_id": "silo.example", + "version": "1.0.0", + "silo_api_version": "v1", + "capabilities": [{ + "type": "request_router.v1", "id": "arr", "display_name": "X", "description": "Y", + "config_schema": [{ + "key": "connection", + "title": "Connection", + "json_schema": "{\"type\":\"object\",\"properties\":{\"a\":{\"type\":\"string\"},\"b\":{\"type\":\"string\"}}}", + "admin_form": { + "fields": [ + {"key":"a","label":"A","control":"ADMIN_FORM_CONTROL_TEXT"}, + {"key":"b","label":"B","control":"ADMIN_FORM_CONTROL_TEXT"} + ], + "sections": ` + sections + ` + } + }] + }] + }`)) + return err + } + if err := load(`[ + {"key":"one","title":"One","field_keys":["a"],"add_group":"slots","add_label":"Add slot"}, + {"key":"two","title":"Two","field_keys":["b"],"add_group":"slots","add_label":"Add slot"}]`); err != nil { + t.Fatalf("Load refused a list of slots: %v", err) + } + for name, sections := range map[string]string{ + "a slot without a label": `[{"key":"one","title":"One","field_keys":["a"],"add_group":"slots"}]`, + "a label without a list": `[{"key":"one","title":"One","field_keys":["a"],"add_label":"Add slot"}]`, + } { + if err := load(sections); err == nil || !strings.Contains(err.Error(), "add_label") { + t.Fatalf("%s: want an add_label error, got %v", name, err) + } + } +} diff --git a/pkg/pluginsdk/manifest/manifest.go b/pkg/pluginsdk/manifest/manifest.go index 5295b05..bff388c 100644 --- a/pkg/pluginsdk/manifest/manifest.go +++ b/pkg/pluginsdk/manifest/manifest.go @@ -420,6 +420,10 @@ func validateRequesterOptions(descriptor *pluginv1.CapabilityDescriptor) error { // call and asks ListRemoteState for pages of that size. const MaxWatchSyncBatchSize = 1000 +// MaxAdminFormAddLabelRunes limits an admin form section's add_label, in +// characters. +const MaxAdminFormAddLabelRunes = 40 + // Limits on RequestRouterWording values, in characters. const ( MaxRequestWordingLabelRunes = 24 @@ -818,6 +822,15 @@ func validateConfigSchema(schema *pluginv1.ConfigSchema) error { if section == nil { continue } + if section.GetAddGroup() == "" && section.GetAddLabel() != "" { + return fmt.Errorf("plugin config schema %q admin_form section %q add_label needs add_group", schema.GetKey(), section.GetKey()) + } + if section.GetAddGroup() != "" { + label := strings.TrimSpace(section.GetAddLabel()) + if label == "" || utf8.RuneCountInString(label) > MaxAdminFormAddLabelRunes { + return fmt.Errorf("plugin config schema %q admin_form section %q add_label must be 1 to %d characters", schema.GetKey(), section.GetKey(), MaxAdminFormAddLabelRunes) + } + } for _, fk := range section.GetFieldKeys() { if _, ok := seen[fk]; !ok { return fmt.Errorf("plugin config schema %q admin_form section %q references unknown field %q", schema.GetKey(), section.GetKey(), fk) diff --git a/proto/silo/plugin/v1/common.proto b/proto/silo/plugin/v1/common.proto index 823eeb7..fbb214d 100644 --- a/proto/silo/plugin/v1/common.proto +++ b/proto/silo/plugin/v1/common.proto @@ -90,6 +90,20 @@ message AdminFormSection { bool collapsed_default = 5; repeated string field_keys = 6; repeated AdminFormCondition show_when = 7; + // add_group makes the section one slot of a list the admin grows. Sections + // with the same add_group are its slots, in form order. The form shows the + // first slot and every slot up to the last one that holds a value other + // than its fields' defaults, then a button that reveals the next slot. The + // slots' fields are ordinary config keys, so the list is as long as the + // sections the plugin declares. The admin can also change the order of the + // slots: two slots trade places by trading the values of their fields at + // the same position in field_keys, so every slot of a list declares the + // same fields in the same order. A slot whose first field is a text field + // shows that value in its header. Empty = an ordinary section. + string add_group = 8; + // add_label is the text of that button, such as "Add storage group". + // Required when add_group is set. + string add_label = 9; } message AdminFormDescriptor { From 65c53aada4d3d7a7b7d5445a005c5fab7bc1cc53 Mon Sep 17 00:00:00 2001 From: Maik Groten Date: Wed, 11 Nov 2026 23:07:05 +0100 Subject: [PATCH 2/2] feat(admin-form): let a multi-select say that the order of its values matters A multi-select stores its values in the order they were chosen, and a host shows the options as a set of toggles. A plugin that reads the values as a sequence, such as folders to fill one after another, gave the admin no way to see or change that order. AdminFormField.ordered marks such a multi-select. A host shows the chosen values as a list the admin can put in order and stores them in that order. Manifest validation allows the flag on a multi-select only. The stored value is the same list either way, and hosts that predate the flag drop it and show the multi-select as before. The comment on AdminFormSection.add_group also says that a host lets the admin remove a slot of a list. AI disclosure: written with Claude Fable 5.2 in Claude Code. go test ./... and go vet pass locally. Co-Authored-By: Claude Fable 5.2 --- docs/compatibility.md | 8 +++++ pkg/pluginproto/silo/plugin/v1/common.pb.go | 26 ++++++++++++--- .../manifest/admin_form_rich_test.go | 32 +++++++++++++++++++ pkg/pluginsdk/manifest/manifest.go | 3 ++ proto/silo/plugin/v1/common.proto | 10 +++++- 5 files changed, 73 insertions(+), 6 deletions(-) diff --git a/docs/compatibility.md b/docs/compatibility.md index 6f8830c..4d4ae36 100644 --- a/docs/compatibility.md +++ b/docs/compatibility.md @@ -208,6 +208,14 @@ install a binary that declares them; install it from an archive there. The slots' fields are ordinary config keys, so nothing changes in what the plugin reads. +`AdminFormField.ordered` says that the order of a multi-select's values +matters. False is the behaviour hosts had before the field existed: the values +are stored in the order they were chosen and cannot be rearranged. Hosts that +predate the field drop it when they install a plugin archive and show the +multi-select as before, and a Silo host that predates it refuses a bare plugin +binary that declares it. The stored value is the same list of values either +way. + `MetadataItem.overview_language` and the `title_language` and `overview_language` fields on `SeasonRecord` and `EpisodeRecord` (added in v0.29.0) are plain strings, like the older `MetadataItem.title_language`. diff --git a/pkg/pluginproto/silo/plugin/v1/common.pb.go b/pkg/pluginproto/silo/plugin/v1/common.pb.go index 78d0297..d8f0187 100644 --- a/pkg/pluginproto/silo/plugin/v1/common.pb.go +++ b/pkg/pluginproto/silo/plugin/v1/common.pb.go @@ -302,8 +302,14 @@ type AdminFormField struct { // group; at most one connection per distinct value of that field may have THIS // field truthy. Empty = no exclusivity. ExclusiveGroupField string `protobuf:"bytes,15,opt,name=exclusive_group_field,json=exclusiveGroupField,proto3" json:"exclusive_group_field,omitempty"` - unknownFields protoimpl.UnknownFields - sizeCache protoimpl.SizeCache + // ordered says the order of a MULTI_SELECT's values matters, such as + // folders that are filled one after another. The host shows the chosen + // values as a list the admin can put in order, and stores them in that + // order. False = the values are a set, in no particular order. Only valid + // on ADMIN_FORM_CONTROL_MULTI_SELECT. + Ordered bool `protobuf:"varint,16,opt,name=ordered,proto3" json:"ordered,omitempty"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache } func (x *AdminFormField) Reset() { @@ -441,6 +447,13 @@ func (x *AdminFormField) GetExclusiveGroupField() string { return "" } +func (x *AdminFormField) GetOrdered() bool { + if x != nil { + return x.Ordered + } + return false +} + // AdminFormCondition: the owning field/section is shown only when, for every // listed condition, the named field's stringified value is in `equals`. type AdminFormCondition struct { @@ -609,7 +622,9 @@ type AdminFormSection struct { // slots: two slots trade places by trading the values of their fields at // the same position in field_keys, so every slot of a list declares the // same fields in the same order. A slot whose first field is a text field - // shows that value in its header. Empty = an ordinary section. + // shows that value in its header. The admin can also remove a slot: the + // slots after it move up one place and the last one is emptied. Empty = an + // ordinary section. AddGroup string `protobuf:"bytes,8,opt,name=add_group,json=addGroup,proto3" json:"add_group,omitempty"` // add_label is the text of that button, such as "Add storage group". // Required when add_group is set. @@ -1668,7 +1683,7 @@ const file_silo_plugin_v1_common_proto_rawDesc = "" + "\x0fAdminFormOption\x12\x14\n" + "\x05value\x18\x01 \x01(\tR\x05value\x12\x14\n" + "\x05label\x18\x02 \x01(\tR\x05label\x12 \n" + - "\vdescription\x18\x03 \x01(\tR\vdescription\"\xf9\x04\n" + + "\vdescription\x18\x03 \x01(\tR\vdescription\"\x93\x05\n" + "\x0eAdminFormField\x12\x10\n" + "\x03key\x18\x01 \x01(\tR\x03key\x12\x14\n" + "\x05label\x18\x02 \x01(\tR\x05label\x12 \n" + @@ -1687,7 +1702,8 @@ const file_silo_plugin_v1_common_proto_rawDesc = "" + "\n" + "validation\x18\x0e \x01(\v2#.silo.plugin.v1.AdminFormValidationR\n" + "validation\x122\n" + - "\x15exclusive_group_field\x18\x0f \x01(\tR\x13exclusiveGroupField\"B\n" + + "\x15exclusive_group_field\x18\x0f \x01(\tR\x13exclusiveGroupField\x12\x18\n" + + "\aordered\x18\x10 \x01(\bR\aordered\"B\n" + "\x12AdminFormCondition\x12\x14\n" + "\x05field\x18\x01 \x01(\tR\x05field\x12\x16\n" + "\x06equals\x18\x02 \x03(\tR\x06equals\"\xc3\x01\n" + diff --git a/pkg/pluginsdk/manifest/admin_form_rich_test.go b/pkg/pluginsdk/manifest/admin_form_rich_test.go index 0ae4263..bb4b3d2 100644 --- a/pkg/pluginsdk/manifest/admin_form_rich_test.go +++ b/pkg/pluginsdk/manifest/admin_form_rich_test.go @@ -364,3 +364,35 @@ func TestSectionAddGroup(t *testing.T) { } } } + +// TestOrderedIsForMultiSelect checks that only a multi-select can say the +// order of its values matters. +func TestOrderedIsForMultiSelect(t *testing.T) { + load := func(control string) error { + _, err := manifest.Load([]byte(`{ + "plugin_id": "silo.example", + "version": "1.0.0", + "silo_api_version": "v1", + "capabilities": [{ + "type": "request_router.v1", "id": "arr", "display_name": "X", "description": "Y", + "config_schema": [{ + "key": "connection", + "title": "Connection", + "json_schema": "{\"type\":\"object\",\"properties\":{\"folders\":{\"type\":\"array\"}}}", + "admin_form": { + "fields": [ + {"key":"folders","label":"Folders","control":"` + control + `","dynamic_options":true,"ordered":true} + ] + } + }] + }] + }`)) + return err + } + if err := load("ADMIN_FORM_CONTROL_MULTI_SELECT"); err != nil { + t.Fatalf("Load refused an ordered multi-select: %v", err) + } + if err := load("ADMIN_FORM_CONTROL_SELECT"); err == nil || !strings.Contains(err.Error(), "ordered") { + t.Fatalf("want an ordered error for a select, got %v", err) + } +} diff --git a/pkg/pluginsdk/manifest/manifest.go b/pkg/pluginsdk/manifest/manifest.go index bff388c..20dc17f 100644 --- a/pkg/pluginsdk/manifest/manifest.go +++ b/pkg/pluginsdk/manifest/manifest.go @@ -812,6 +812,9 @@ func validateConfigSchema(schema *pluginv1.ConfigSchema) error { return fmt.Errorf("plugin config schema %q admin_form field %q show_when references unknown field %q", schema.GetKey(), key, cond.GetField()) } } + if field.GetOrdered() && field.GetControl() != pluginv1.AdminFormControl_ADMIN_FORM_CONTROL_MULTI_SELECT { + return fmt.Errorf("plugin config schema %q admin_form field %q ordered is only for a multi-select", schema.GetKey(), key) + } if eg := field.GetExclusiveGroupField(); eg != "" { if !hasReference(eg) { return fmt.Errorf("plugin config schema %q admin_form field %q exclusive_group_field references unknown field %q", schema.GetKey(), key, eg) diff --git a/proto/silo/plugin/v1/common.proto b/proto/silo/plugin/v1/common.proto index fbb214d..af0b8fa 100644 --- a/proto/silo/plugin/v1/common.proto +++ b/proto/silo/plugin/v1/common.proto @@ -59,6 +59,12 @@ message AdminFormField { // group; at most one connection per distinct value of that field may have THIS // field truthy. Empty = no exclusivity. string exclusive_group_field = 15; + // ordered says the order of a MULTI_SELECT's values matters, such as + // folders that are filled one after another. The host shows the chosen + // values as a list the admin can put in order, and stores them in that + // order. False = the values are a set, in no particular order. Only valid + // on ADMIN_FORM_CONTROL_MULTI_SELECT. + bool ordered = 16; } // AdminFormCondition: the owning field/section is shown only when, for every @@ -99,7 +105,9 @@ message AdminFormSection { // slots: two slots trade places by trading the values of their fields at // the same position in field_keys, so every slot of a list declares the // same fields in the same order. A slot whose first field is a text field - // shows that value in its header. Empty = an ordinary section. + // shows that value in its header. The admin can also remove a slot: the + // slots after it move up one place and the last one is emptied. Empty = an + // ordinary section. string add_group = 8; // add_label is the text of that button, such as "Add storage group". // Required when add_group is set.