RFC: Plugin-Registrable Actions

[hidden4003]

Plugin-Registerable Actions — Spec (v5, replaces parameterless Execute with a unified context/parameter model)

Changelog from v4: PR #1383 — the reference implementation for v4 — was closed, not merged. Building it surfaced that "Execute stays fully parameterless" (Gap 18) doesn't survive contact with two things v4 treated as settled: mandatory async queueing (Gap 15) and the real shape of the ~30 actions being migrated (Gap 12/13). This revision reopens and resolves those, plus three gaps v4 didn't know it needed.

1. Gap 18 (reopened): Parameterless Execute assumed a "current execution context" service could hand a queued job its series/group/episode context via ambient DI scope (v4's own words: "an implementation detail, not a further open design gap"). It isn't a detail — IQueueJob.Process() runs from JobDataJson, not from a live request scope, so there is no ambient context by the time a worker picks the job up. This is why the implementation abandoned parameterless Execute for typed sub-interface parameters instead, which then broke Gap 8's permission model (see Allow browse for folder on import folder #2).
2. Gap 8/19 (reopened): v4 restored Permission as an orthogonal property. The implementation folded it back into ActionScope as 8 *System/*User variants — a direct consequence of Missing relations group filter #1's interface churn, not an independent decision. Reopened here to re-confirm the orthogonal design and make it survive the fix to Missing relations group filter #1.
3. Gap 23 (new): Free-form invocation parameters. Several actions being migrated take real per-invocation options that are neither scope context nor a CancellationToken — SyncVotes(bool export, bool import), PurgeAllTmdbLinks(bool removeShowLinks, bool removeMovieLinks, bool? resetAutoLinkingState), DownloadAllImages(...), PurgeAllUsedReleases(bool skipEvents, HashSet<string>? providerNames), RemoveMissingFiles(bool removeFromMyList). No version of Execute's signature — v4's or the PR's — had anywhere for these to go. Never previously raised as a gap.
4. Gap 24 (new): Synchronous pre-invoke feedback. Several actions today reject bad requests before doing any work (AVDumpMismatchedFiles 400s if the AVDump key is missing; SyncVotes 400s on conflicting flags or a non-AniDB user). Gap 10's "always logged as a queue job failure" silently drops this to server logs. Never previously raised as a gap.
5. Gap 25 (new): Post-execution result reporting. AddAllManualLinksToMyList and VerifyAllRelations return counts today ("Saved 42 AddToMyList Commands", { ScheduledJobs: 5 }). Gap 7's "no tracking ID, just acknowledge the enqueue" drops this. Never previously raised as a gap.
6. Gap 12/13 (corrected, not reopened): "Port all at once... known to be a few, non-blocking" undercounts the work. Of the ~30 actions in ActionController today, roughly 20 bypass the queue entirely via raw Task.Run/Task.Factory.StartNew — migrating them means writing real queue-backed implementations, not just wrapping existing job types.
7. Gap 26 (new): Calling-user identity. SyncVotes acts on User.JMMUserID — the identity of whoever is logged in and made the call — which is a different thing from a Series/Group/Episode scope target, and different again from a User-permission action's subject user (e.g. "sync Plex for user X"). No existing gap covers "who invoked this," as opposed to "what is this about."

Problem & Goal

Unchanged from v4 — see discussion #1380 for the original framing. This revision only changes how actions receive context and parameters, and how the API surfaces validation/results around mandatory queueing.

Proposed interface

public interface IExecutableAction
{
    string Name { get; }
    string? Description => null;
    ActionCategory Category => ActionCategory.PluginInferred; // unchanged from v4/PR consensus — see Gap 1
    ActionPermission Permission { get; } // no default — every action must state this explicitly (see Gap 8/19)

    /// <summary>
    /// Optional synchronous pre-check, run by the API before enqueueing. Return a
    /// non-null result to reject the invocation immediately (e.g. HTTP 400) without
    /// ever touching the queue. Default: always allowed.
    /// </summary>
    Task<ActionValidationResult?> Validate(CancellationToken token = default) => Task.FromResult<ActionValidationResult?>(null);

    Task Execute(CancellationToken token = default);
}

public sealed record ActionValidationResult(string Reason);

public enum ActionScope { Global, Group, Series, Episode }
public enum ActionPermission { Admin, User }

Category, its default (PluginInferred), and the decision not to add a central per-category description field are carried forward unchanged from the PR #1383 discussion thread — @harshithmohan and @revam already reached consensus on both ("Leave it off then"). Not reopened here.

Scope & context — replaces v4's Scope property and the PR's 8 marker interfaces

Four lightweight base classes, one per entity level. Global needs no context and implements IExecutableAction directly; the other three carry a typed, framework-populated context via an explicitly-implemented interface method, invisible on the class's own public surface:

public interface IScopedAction
{
    void SetContext(object context); // called by the framework only, before Execute
}

public abstract class SeriesAction : IExecutableAction, IScopedAction
{
    public ActionScope Scope => ActionScope.Series;
    protected IShokoSeries Series { get; private set; } = null!;
    void IScopedAction.SetContext(object context) => Series = (IShokoSeries)context;

    public abstract ActionPermission Permission { get; }
    public abstract Task Execute(CancellationToken token = default);
}
// GroupAction / EpisodeAction follow the same pattern, over IShokoGroup / IShokoEpisode.

A plugin author writing a series-scoped action never sees SetContext — they just reference Series inside Execute, already non-null:

public class RefreshSeriesFromProviderAction : SeriesAction
{
    public override ActionPermission Permission => ActionPermission.Admin;
    public Task Execute(CancellationToken token) { /* Series is populated */ }
}

Why 4 base classes instead of 8 interfaces: Permission stays its own orthogonal property (per reopened Gap 8/19), so scope and permission are no longer multiplied together. This also restores the RFC's original two-axis design intent without losing the compile-time non-null guarantee that motivated the PR's sub-interface split in the first place — Execute never has to null-check its own context, it just doesn't have a public setter for it.

Free-form parameters — resolves Gap 23

Ordinary public settable properties on the action instance, populated the same way IQueueJob properties already are from JobDataJson — the invoke endpoint's request body is deserialized onto the instance via Newtonsoft's PopulateObject (the serializer already backing the rest of the API). Because SetContext is an explicit interface implementation, a request body can't accidentally overwrite scope context by naming a field the same as the protected property.

public class PurgeAllTmdbLinksAction : IExecutableAction
{
    public ActionPermission Permission => ActionPermission.Admin;
    public bool RemoveShowLinks { get; set; } = true;
    public bool RemoveMovieLinks { get; set; } = true;
    public bool? ResetAutoLinkingState { get; set; }

    public Task Execute(CancellationToken token) { /* uses the properties above */ }
}

Invoke request: POST /Actions/{id}/Execute with a JSON body matching the action's own settable properties. Actions with no free-form parameters simply ignore any body sent.

Synchronous validation — resolves Gap 24

Validate runs on the API thread, before anything is enqueued. A non-null result means the invoke endpoint returns 400 with the given Reason and never touches the queue:

public class SyncVotesAction : IExecutableAction
{
    public ActionPermission Permission => ActionPermission.User;
    public bool Export { get; set; }
    public bool Import { get; set; }

    public Task<ActionValidationResult?> Validate(CancellationToken token)
    {
        if (Export && Import)
            return Task.FromResult<ActionValidationResult?>(new("Cannot export and import at the same time."));
        return Task.FromResult<ActionValidationResult?>(null);
    }

    public Task Execute(CancellationToken token) { ... }
}

Checks that depend on the calling user (e.g. today's User.IsAniDBUser != 1 check) use the calling-user context described below — Validate receives it the same way Execute does.

Calling-user identity — resolves Gap 26

Distinct from Scope's entity context and from a User-permission action's subject. Any action — regardless of scope — can opt in to knowing who invoked it by implementing a small marker interface, populated by the framework the same way IScopedAction.SetContext is:

public interface IActionCaller
{
    void SetCaller(IUser caller); // called by the framework only, before Validate/Execute
}

SyncVotesAction above would implement this to replace today's User.JMMUserID/User.IsAniDBUser checks. This is additive and orthogonal to everything else — most actions won't need it.

Registration & validation at plugin load — recovers compile-time safety as load-time safety

Plugins are reflection-loaded regardless of design, so nothing here was ever compiler-checked. ActionService.AddParts (called from PluginManager.InitPlugins, same place GetExports<IExecutableAction> already runs today) validates each registered type at startup and fails fast with a named error, not a null-reference three weeks into production:

• A type whose declared Scope (via its base class) doesn't match what it derives from — rejected.
• Permission not overridden — rejected (no silent default; every action author must choose).
• This is also how Gap 20 ("reject invocation via the wrong route") gets enforced: ActionService knows each action's scope at registration time, so POST /Series/{id}/Actions/{actionId}/Execute against a type that isn't a SeriesAction 400s immediately — no per-request reflection needed.

Execution service — one generic wrapper job

A single ActionExecutionJob : IQueueJob handles every action, so plugins never write their own job class:

1. Resolves the target IExecutableAction instance from DI (transient, per Gap 9 — unchanged).
2. Populates its free-form properties from JobDataJson.
3. If scoped, resolves the entity (e.g. AnimeSeries by ID, also carried in JobDataJson) via the existing repositories and calls SetContext.
4. If it implements IActionCaller, resolves the calling IUser and calls SetCaller.
5. Calls Execute.

Result reporting — resolves Gap 25, no new response shape

Rather than reintroducing a tracking ID or a synchronous result payload (both intentionally dropped in v4 Gap 7, and that reasoning still holds for the invoke response), post-execution results use IQueueJob.Details — the Dictionary<string, object> field that already exists for queue display purposes — populated by ActionExecutionJob after Execute completes. The queue system already bridges job lifecycle to SignalR (QueueStateEventHandler → QueueEventEmitter → AggregateHub), which the Actions UI needs anyway per Gap 15's "progress/status visible" requirement. "Saved 42 AddToMyList Commands" becomes a Details entry surfaced through that existing channel instead of an HTTP response body.

Migration — corrects Gap 12/13's effort estimate

Of the ~30 actions in ActionController.cs today, the roughly 20 that currently run via raw Task.Run/Task.Factory.StartNew (bypassing the queue entirely — e.g. PurgeAllTmdbLinks, RecreateAllGroups, UpdateAllTmdbShows, DownloadAllImages) need actual queue-backed IExecutableAction implementations written, not just interface conformance. This is real, sequenceable implementation work, not a "known to be a few, non-blocking" bookkeeping pass — v4's Gap 13 estimate was wrong. Recommend inventorying these ~20 explicitly as part of implementation planning (reopens the "no inventory needed" part of Gap 13 specifically for this reason), each noting its real current Permission, same requirement v4 already stated for the ones that were already job-backed.

Unchanged from v4

• ID scheme (UUIDv5, plugin-ID-namespaced) — Gap 4/5/21.
• Listing endpoint shape (B2, array of category objects with nested actions + permission) — Gap 6, extended with the same field for scope's base-class-derived value.
• Mandatory queueing, no direct-execution API path — Gap 15.
• No redesign of the Actions menu UI beyond consuming permission — Gap 16.
• IExecutableAction naming — Gap 17.
• Migration keeps old endpoints deprecated-but-running in parallel — Gap 12 (rollout order unchanged; only the effort estimate is corrected).

---

Gap tracker (v5 deltas only — v4's Gaps 1–7, 9–17, 20–22 carry forward unchanged)

No.	Topic	Status
8/19	Permission modeling	✅ Reopened & re-resolved — restored as an orthogonal property, now required (no default); survives the Gap 18 fix without re-folding into Scope
18	Series/group/episode-scoped execution model	✅ Reopened & re-resolved — parameterless Execute dropped as unworkable under mandatory async queueing; replaced by typed context via 4 scope base classes + explicit-interface SetContext, invisible to the plugin author
23	Free-form invocation parameters	✅ New, resolved — ordinary settable properties, populated from the invoke request body the same way IQueueJob properties are populated from JobDataJson
24	Synchronous pre-invoke validation	✅ New, resolved — optional Validate method, runs before enqueue, can 400 without touching the queue
25	Post-execution result/feedback reporting	✅ New, resolved — reuses IQueueJob.Details + existing SignalR queue events, no new response shape
26	Calling-user identity vs. scope context	✅ New, resolved — separate opt-in IActionCaller marker, orthogonal to Scope and to User-permission's subject
12/13	Migration effort estimate	⚠️ Corrected — ~20 of ~30 existing actions bypass the queue today and need real implementations, not just interface wrapping; inventorying them is back in scope

7 items touched in v5 (2 reopened, 4 newly added, 1 corrected); all other v4 gaps stand as previously 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.