docs(plugins): clarify permission requirements for non-built-in plugins#299
Open
dsaenztagarro wants to merge 1 commit intozellij-org:mainfrom
Open
docs(plugins): clarify permission requirements for non-built-in plugins#299dsaenztagarro wants to merge 1 commit intozellij-org:mainfrom
dsaenztagarro wants to merge 1 commit intozellij-org:mainfrom
Conversation
Add guidance across three documentation pages explaining that plugins loaded via file: or http(s): must call request_permission() in their load() function, unlike built-in zellij: plugins which bypass permission checks entirely. Without this call, privileged API commands are silently denied, causing plugin panics.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
When forking a built-in plugin (e.g.
session-manager) and loading it viafile:, the plugin crashes because built-in plugins never callrequest_permission()— they bypass permission checks entirely viais_builtin(). This is not documented anywhere, making it a common pitfall.This PR adds guidance across three documentation pages:
plugin-api-permissions.md— New "How permissions work" section explaining the difference between built-in (zellij:) and non-built-in (file:,http(s):) plugins, with a code example and a callout for plugin forkingplugin-aliases.md— Warning when swapping default aliases tofile:pluginsplugin-lifecycle.md— Note in theload()section that non-built-in plugins must request permissionsMotivation
I forked
session-managerto add custom keybindings, loaded it viafile:in the plugin aliases, and it crashed with a panic atzellij-tile/src/shim.rs(bytes_from_stdin().unwrap()on<NO PAYLOAD>). The root cause:CurrentSessionLastSavedTimerequiresReadApplicationState, which was silently denied because the plugin never calledrequest_permission(). The host writes no response on denial, so the plugin panics reading from empty stdin.This took significant debugging to trace through the permission check logic in
zellij_exports.rs. A note in the docs would save others the same effort.