RFC: Plugin-Registrable Actions

[hidden4003]

Plugin-Registerable Actions — Spec (v3, adds series-scoped actions)

Problem

Right now the Actions menu in the web UI is a fixed, server-hardcoded list. Plugins have no way to add entries to it. As we add more provider-style plugins (AniZip, and potentially a Relay integration), each needs a way to expose "run this thing on demand" behavior to the user without core needing to know about it in advance.

Goal

Let plugins (and core, by migrating existing actions to the same shape) register discrete, invokable units of work — "actions" — that:

• show up in the Actions menu automatically,
• can be triggered from the API by ID,
• always run through the job queue so progress/status is visible (see Queue integration — Gap 15),
• rely on the queue system itself for concurrency handling, rather than a per-action opt-in flag (see Gaps 3 & 14).

Proposed interface

public enum ActionCategory
{
    Generic, // default fallback if an action doesn't specify one
    // ... remaining core-defined categories ...
}
public enum ActionScope

{

Global,

Series

}
public interface IExecutableAction

{

Guid Id { get; } // UUIDv5, derived deterministically (see Identity section)

string Name { get; }

ActionCategory Category => ActionCategory.Generic;

string? Description => null;

ActionScope Scope { get; }

Task Execute(CancellationToken token = default);

}

Category is a hard-validated enum (Gap 1 — resolved), not a free string. Generic is a member of the same enum and is the default when an action doesn't specify a category. Each enum value's display name/description is owned centrally by core (not supplied per-plugin) — a plugin cannot introduce a new category at runtime; adding a genuinely new category requires a PR against core to extend the enum.

Scope (Gap 20 — resolved) declares whether an action is Global or Series. The framework uses this to decide which listing endpoint (/Actions vs. /Series/{seriesID}/Actions) the action appears under, and which route can invoke it.

Enabled and AllowConcurrentExecution dropped for v1 (Gaps 2 & 3 — resolved). Deemed not worth the implementation effort right now; can be reconsidered later if a real need shows up. Concurrency is handled implicitly — see Queue integration below.

Name finalized: IExecutableAction (Gap 17 — resolved).

Display metadata

• Name / Category / Description — display metadata for the UI.
• Categories: hard-validated enum. (Gap 1 — ✅ resolved.) Category is a fixed enum (ActionCategory), not a free string.
  • Generic is a member of that same enum and is the default/fallback for any action that doesn't specify a category.
  • Each enum value's display name/description is owned centrally by core — plugins do not supply a category description, so the earlier "description precedence when names collide" concern is now moot (there's no plugin-supplied description to conflict with).
  • A plugin cannot invent a new category at runtime. Adding a genuinely new category requires a PR against core to extend the ActionCategory enum — this is now a hard technical constraint, not just a documented convention.

Enabled (Gap 2 — ✅ resolved) and AllowConcurrentExecution (Gap 3 — ✅ resolved)

Both dropped from v1. Consensus from the proposal author: not worth the implementation effort right now.

• No visibility-gating mechanism on the interface for v1 — a plugin that wants to conditionally no-op can implement that inside Execute itself.
• No advisory concurrency flag on the interface. Concurrency protection instead falls naturally out of the now-mandatory queue execution model (see Queue integration) — the queue system handles serialization/concurrency, so the interface doesn't need to declare intent about it.
• Both can be reconsidered post-v1 if a concrete need emerges.

Identity / API shape

• ID scheme: UUIDv5 (Gap 4 — resolved), deterministically derived from the action's fully-qualified class name (Namespace.ClassName).
• IDs are not stable across plugin refactors. If a plugin renames or moves the class, the derived UUID changes. This is accepted, not a bug — must be explicitly documented so plugin authors know renaming a class changes its action ID. (Gap 5 — resolved as a documentation requirement, not a design change.)
  • Rationale for accepting this instead of introducing a separate stable key: an explicit key field would require managing key collisions across all actions from all active plugins; deriving from namespace+class name makes accidental collisions between unrelated plugins far less likely.
• Listing endpoint shape — ✅ Resolved (Gap 6): B2, array of category objects.
  • Now that Category is a hard enum (Gap 1), the category-id/slug question is resolved implicitly — the enum value itself is the canonical, stable identifier, and its name/description are looked up centrally rather than carried per-action.
  • Chosen shape:

    [
      {
        "name": "Generic",
        "description": "Miscellaneous actions",
        "actions": [
          {
            "id": "3d813cbb-47fb-32ba-91df-831e1593ac29",
            "name": "Restart Service",
            "description": "Restarts the background worker service"
          }
        ]
      }
    ]
    

  • name/description on each category object come from the enum's central definition (Gap 1), not from any individual action or plugin.
• Invoke endpoint: POST /actions/{id}/execute (or similar). ✅ Resolved (Gap 7)
  • No tracking ID returned. The invoke endpoint enqueues the job and acknowledges (success/failure of the enqueue, not the eventual job result) with no further payload. The earlier tracking-ID concept is dropped — it had no remaining consumer once immediate results (Gap 15) and per-action UI concurrency surfacing (Gap 3) were both removed from v1.
• Auth/permissions: all actions require admin privileges. (Gap 8 — resolved.) No per-action role granularity for v1.

Registration & DI

• Plugins register IExecutableAction implementations via the existing plugin DI hookup; constructor dependencies resolve normally.
• Lifetime: ephemeral/transient. (Gap 9 — resolved.) The service asks DI for an instance each time it iterates/invokes; it does not manage lifetime itself. If a plugin wants singleton behavior (e.g. to persist state across Execute calls), it must declare that itself in its own DI registration — maintaining state between invocations is explicitly the plugin's responsibility, not the framework's.

Execution service

A small dedicated service (e.g. ActionService) enumerates registered actions, exposes them to the API/UI layer, and runs one by ID — always by scheduling it through the existing job/queue system (queueing is mandatory, see Queue integration below; there is no separate concurrency-tracking responsibility since the queue owns that). It does not live on an existing service (e.g. not bolted onto the job scheduler).

• Error handling — ✅ Resolved (Gap 10), consequence of mandatory queueing: since every action always runs through the queue, errors are always logged the same way as any other queued job failure. The "surfaced directly to caller" branch no longer applies — there is no non-queued path.
• Timeout/cancellation policy — ✅ Resolved (Gap 11):
  • Since execution is always queued (Gap 15), cancellation tokens are queue/system-lifecycle bound rather than request-bound — there's no request to bind to since there's no direct-execution path.
  • No separate hardcoded action-level timeout needed. The existing job queue already has its own long-running-job detection: it doesn't kill a job (not really feasible in .NET), but it flags/logs when a job has been alive unusually long as a likely deadlock/stuck state. Since actions are always queued, they inherit this behavior automatically — no additional mechanism required on IExecutableAction or ActionService.

Migrating existing actions

• Resolved (Gap 12): Old hardcoded actions are not removed immediately. All existing actions are ported to IExecutableAction at once (not incremental). The old endpoint(s) are kept and marked deprecated, run in parallel with the new endpoint for a grace period so the frontend can migrate, and are removed in a later release.
• Resolved (Gap 13): No inventory of existing actions will be compiled ahead of time; known to be "a few," not currently blocking.

Concurrency

• Resolved (Gap 14) — now largely moot: With AllowConcurrentExecution dropped (Gap 3) and queue execution mandatory (Gap 15), ActionService no longer needs its own per-action-type concurrency guard — the queue system handles serialization/concurrency for jobs itself. Actions remain confirmed parameterless (aside from the optional CancellationToken), so if the queue's own concurrency handling ever needs an identity key, it's the action UUID alone.

Queue integration — ✅ Resolved (Gap 15)

Reversed from the earlier opt-in lean. Per the main server maintainer: every action execution is enforced to run as a queued job. There is no direct/immediate execution path exposed by ActionService — the API always enqueues.

Rationale: if actions go through the queue unconditionally, the queue system handles concurrency itself, removing the need for a separate AllowConcurrentExecution mechanism (ties back into Gaps 2/3/14 being dropped/simplified).

Note: this governs execution via ActionService/the API. It doesn't prevent a plugin from calling its own Execute method directly in-process if it wants to bypass the service entirely — that's just a plugin calling its own code, not something the framework mediates either way.

UI

Keep the current Actions menu UI, data-driven off the new listing endpoint.

• Resolved (Gap 16): No redesign needed for v1, unless categories become multi-level (e.g. nested categories) — in which case revisit.

Naming

• Resolved (Gap 17): IExecutableAction, no objections raised.

Series-scoped actions (new scope — Gaps 18–20)

New requirement: actions also need to exist scoped to a specific series, alongside the existing global actions. Proposed endpoints, mirroring the existing /Series/{seriesID} resource pattern:

• Listing: GET /Series/{seriesID}/Actions
• Invoke: POST /Series/{seriesID}/Actions/{id}/Execute

This is new surface area, not just a gap fill, and it opens several design questions the current interface doesn't answer:

• Gap 18 — ✅ Resolved — Execution model. Execute stays fully parameterless, as originally confirmed (Gap 14) — there is no seriesId argument added to the signature. For a Scope: Series action, the series ID comes from the URL route (/Series/{seriesID}/Actions/{id}/Execute), not as a method parameter. The exact mechanism by which the action itself accesses that route-supplied series ID during Execute (e.g. an injected scoped "current execution context" service resolved by DI per invocation, consistent with the existing transient-per-invoke lifetime from Gap 9) is an implementation detail, not a further open design gap — worth documenting precisely when implemented, but not blocking.
  • Identity scheme unaffected: one UUIDv5 per action class regardless of scope; the route supplies the series context separately.
• Gap 19 — ✅ Resolved — Permissions for series-scoped actions. Series actions use the same admin-only permission model as global actions (Gap 8) — no separate/looser model. Rationale: series-scoped actions operate on global/shared library objects (the series entity itself), not on anything user-specific, so there's no basis for opening them to non-admin users.
• Gap 20 — ✅ Resolved — Registration/listing model for scope. Actions declare an explicit Scope (Global or Series) on the interface itself (see Proposed interface above). The framework uses this to route an action to the correct listing endpoint (/Actions vs. /Series/{seriesID}/Actions) and to reject invocation via the wrong route. Whether the series listing endpoint reuses whichever shape wins Gap 6 (B1/B2) is still assumed but not explicitly reconfirmed for the series case.

---

Gap tracker (v3)

No.	Topic	Status
1	Category naming collisions between plugins/core	✅ Resolved — Category is a hard-validated enum; Generic is the default fallback member of the same enum; new categories require a core PR
2	Enabled — dynamic vs. cacheable/push vs. drop entirely	✅ Resolved — dropped for v1, not worth the effort
3	AllowConcurrentExecution — surfaced in UI or silent guard	✅ Resolved — dropped for v1, not worth the effort
4	ID scheme — class name vs. UUID	✅ Resolved — UUIDv5, deterministic
5	ID stability across plugin refactors/renames	✅ Resolved — not stable, must be documented
6	Flat list vs. dict API shape + category metadata	✅ Resolved — B2 chosen: array of category objects, each with name/description (from the enum) and a nested actions array
7	Invoke response shape — immediate result vs. job/tracking ID	✅ Resolved — no tracking ID returned; endpoint just acknowledges the enqueue
8	Auth/permissions model per action	✅ Resolved — admin-only, no per-action roles (global actions only — see Gap 19 for series-scoped)
9	DI lifetime/scope for action instances	✅ Resolved — transient; statefulness is plugin's own responsibility
10	Error handling contract when Execute throws	✅ Resolved — always logged as a queue job failure, consequence of Gap 15
11	Timeout/cancellation policy	✅ Resolved — existing queue's stuck-job detection (flags long-lived jobs as likely deadlocks; can't force-kill in .NET) covers this automatically since actions are always queued; no separate action-level timeout needed
12	Migration rollout order	✅ Resolved — port all at once, old endpoints deprecated then removed later
13	Full inventory of existing actions	✅ Resolved — not doing one, non-blocking
14	Concurrency scope — confirm parameterless	✅ Resolved — parameterless confirmed for both global and series-scoped actions (series ID comes from the route, not a parameter); largely moot since queue now handles concurrency
15	Queue integration — mandatory, opt-in, or deferred	✅ Resolved — mandatory; every action always runs as a queued job, no direct-execution API path
16	UI — confirm no-redesign-for-v1	✅ Resolved — no redesign unless multi-level categories introduced
17	Final interface name	✅ Resolved — IExecutableAction
18	Series-scoped action execution model (new)	✅ Resolved — stays parameterless; series ID comes from the route, not Execute's signature; exact in-process access mechanism is an implementation detail, not a blocking design gap
19	Series-scoped action permissions (new)	✅ Resolved — same admin-only model as global actions; series actions operate on global/shared objects, not user-specific ones
20	Series-scoped action registration/listing model (new)	✅ Resolved — actions declare Scope (Global/Series) on the interface; still assumes but hasn't reconfirmed reuse of Gap 6's listing shape for the series endpoint

All 20 gaps resolved. 🎉

[revam]

Gap 1, i was thinking free form so plugins can pick the same categories as the core if they want to.

Gap 2, dynamic.

Gap 3, we could surface it, if we want to support it in the first place.

gap 4, I'd lean on UUIDs

gap 5, obviously the id would change if the class name changes. that was intentional in the proposal i made in chat, but if you want stable ids across refactors and renames then we can introduce a new key or id field, in which the id is either used as is, or derived from. but now we need to manage key/id collision across all actions across all active plugins, whereas if we leave it on auto inferred from the class name (+ namespace) then there will be less likely that there would be collisions from different plugins.

gap 6, for api shape, then whatever you (@hidden4003) or @harshithmohan wants will do.

gap 7, depends on what we want

gap 8. all actions would require admin. privileges, as normal users shouldn't need to nor have the right to run them. if someone disagrees then we can take it from there.

gap 9, ephemeral instances, created when iterated through the service. if a plugin wants a singleton, they can declare it as such. we only ask the DI to initialize or grab an instance for us to use, so not our concern.

gap 10, depending on if we run it in the queue or not. if it's ran in the queue, then we log it the same way as when running in the queue. if we run it directly, then we can surface it to the client or caller.

gap 11, cancellation would be set by the caller. so for direct calls by a client, then would be bound to the request timeout/abort, whereas for other plugins it would be whatever they decide. timeout would just be a cancellation token which cancels after a set time.

gap 12, we won't remove the older actions, but we'll port all of them to use the newer system at once, so there will be a grace period where both the older actions and new actions will function for the client to implement it's needed changes to use the newer system.

gap 13, no need to document here. just know there are a few.

gap 14, everything would be parameterless (except the cancellation token, which is optional), but there could still be actions to run which depends on other factors than caller parameters.

gap 15, I'd lean on opt-in, so the service has a direct call and schedule in queue, and the client can decide to run it then and there, or run it in the queue. if ran then and there, then the cancellation token will be tied to the request, but if ran in the queue, then it would be tied to the system uptime or just not set.

gap 16, that's for you (@hidden4003) and @harshithmohan to decide if you want to change it or keep it.

gap 17, IExecutableAction seems fine to me unless someone has anything else.

[hidden4003]

Same goes for someone doing a typo in a category name and we get double categories. I can only come up with an idea of a whitelist, plugin can pick from it or it goes to generic category (for example"Plugins") with action name being prefixed.

[hidden4003]

Another idea is to make a table for categories and populate it with current categories, treat is as whitelist but later give user ability to re-arrange, rename and edit descriptions and create categories however they want.

[hidden4003]

@revam what about the hardcoded timeout?

[harshithmohan]

What's a hardcoded timeout? 🤔

Also, we forgot, there are series level actions as well, shouldn't we implement them in the same way?

[hidden4003]

Timeout for the plugin action in case the plugin author doesn't bother with one and action just keeps going forever.

[harshithmohan]

But we could

…

On Wed, Jul 8, 2026, 20:01 hidden4003 ***@***.***> wrote: we currently have descriptions for actions, not for categories — Reply to this email directly, view it on GitHub <#1380?email_source=notifications&email_token=AGGOKQTIKRWMT5A4IXYVXV35DZLLVA5CNFSNUABIM5UWIORPF5TWS5BNNB2WEL2ENFZWG5LTONUW63SDN5WW2ZLOOQXTCNZVG4ZTQOJXUZZGKYLTN5XKO3LFNZ2GS33OUVSXMZLOOSWGM33PORSXEX3DNRUWG2Y#discussioncomment-17573897>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AGGOKQUIA3HWTISLBZSKGA35DZLLVAVCNFSNUABHKJSXA33TNF2G64TZHMZDEOJXHE4DQOB3IRUXGY3VONZWS33OHMYTAMZYGE3TQMFBOYBA> . You are receiving this because you were mentioned.Message ID: ***@***.*** com>

[hidden4003]

we could, you would need to give more details than that

[bigretromike]

will this be User Based/Profile-like settings for plugins ? or it all-for-one ?

[bigretromike]

I'm asking if the configuration of those plugins are configured per Profile/User or global for whole server (or maybe this question is stupid because user profiles are removed from 6.0.0 for example)

If I login with SFW profile will I be able to interact with "future" plugins that include non-sfw content ?

[hidden4003]

Plugins are not per-user therefore this will not be per-user either.

[da3dsoul]

In addition, actions are generally admin commands, so it doesn't make a ton of sense to make them per user

[harshithmohan]

In addition, actions are generally admin commands, so it doesn't make a ton of sense to make them per user

It does. Imagine you had a plugin for MAL sync, if it was per user and there's an action for "Force sync".

[hidden4003]

In v1 version of the feature actions are admin only.