public inbox for pve-devel@lists.proxmox.com
 help / color / mirror / Atom feed
From: "Max R. Carrara" <m.carrara@proxmox.com>
To: pve-devel@lists.proxmox.com
Cc: Alfonso Kuen <gerencia@idkmanager.com>,
	Thomas Ellmenreich <t.ellmenreich@proxmox.com>,
	Jakob Klocker <j.klocker@proxmox.com>
Subject: [PATCH pve-storage v5 02/19] api: plugins/storage: add initial routes and endpoints
Date: Fri, 13 Nov 2026 21:33:06 +0100	[thread overview]
Message-ID: <20261113203330.932813-3-m.carrara@proxmox.com> (raw)
In-Reply-To: <20261113203330.932813-1-m.carrara@proxmox.com>

Add the following routes / endpoints:

* `GET plugins/storage`
  Directory index, listing the direct child path components (so,
  just 'plugin' currently).

* `GET plugins/storage/plugin`
  Lists all installed storage plugins and their metadata.
  Currently, this is just an array of objects, with each object
  containing the plugin's `type()` and `origin` -- the latter saying
  whether a plugin is "builtin" or "custom". It is also possible to
  filter plugins by their `origin`, i.e. to only list built-in or
  custom plugins.

* `GET plugins/storage/plugin/{type}`
  Returns the metadata for a single plugin given by `{type}`.

Signed-off-by: Max R. Carrara <m.carrara@proxmox.com>
---
 src/PVE/API2/Makefile                  |   1 +
 src/PVE/API2/Plugins/Makefile          |  18 ++++
 src/PVE/API2/Plugins/Storage.pm        |  58 +++++++++++
 src/PVE/API2/Plugins/Storage/Makefile  |  17 ++++
 src/PVE/API2/Plugins/Storage/Plugin.pm | 128 +++++++++++++++++++++++++
 5 files changed, 222 insertions(+)
 create mode 100644 src/PVE/API2/Plugins/Makefile
 create mode 100644 src/PVE/API2/Plugins/Storage.pm
 create mode 100644 src/PVE/API2/Plugins/Storage/Makefile
 create mode 100644 src/PVE/API2/Plugins/Storage/Plugin.pm

diff --git a/src/PVE/API2/Makefile b/src/PVE/API2/Makefile
index fe316c52..01b7b28f 100644
--- a/src/PVE/API2/Makefile
+++ b/src/PVE/API2/Makefile
@@ -3,5 +3,6 @@
 .PHONY: install
 install:
 	install -D -m 0644 Disks.pm ${DESTDIR}${PERLDIR}/PVE/API2/Disks.pm
 	make -C Storage install
 	make -C Disks install
+	make -C Plugins install
diff --git a/src/PVE/API2/Plugins/Makefile b/src/PVE/API2/Plugins/Makefile
new file mode 100644
index 00000000..f59e75b6
--- /dev/null
+++ b/src/PVE/API2/Plugins/Makefile
@@ -0,0 +1,18 @@
+SOURCES = Storage.pm		\
+
+
+SUBDIRS = Storage		\
+
+
+INSTALL_PATH = ${DESTDIR}${PERLDIR}/PVE/API2/Plugins
+
+
+.PHONY: install
+install:
+	set -e && for SOURCE in ${SOURCES}; \
+		do install -D -m 0644 $$SOURCE ${INSTALL_PATH}/$$SOURCE; \
+	done
+	set -e && for SUBDIR in ${SUBDIRS}; \
+		do make -C $$SUBDIR install; \
+	done
+
diff --git a/src/PVE/API2/Plugins/Storage.pm b/src/PVE/API2/Plugins/Storage.pm
new file mode 100644
index 00000000..e7547a04
--- /dev/null
+++ b/src/PVE/API2/Plugins/Storage.pm
@@ -0,0 +1,58 @@
+package PVE::API2::Plugins::Storage;
+
+use v5.36;
+
+use PVE::RESTHandler;
+
+use PVE::API2::Plugins::Storage::Plugin;
+
+use base qw(PVE::RESTHandler);
+
+__PACKAGE__->register_method({
+    subclass => 'PVE::API2::Plugins::Storage::Plugin',
+    path => 'plugin',
+});
+
+# plugins/storage
+
+__PACKAGE__->register_method({
+    name => 'index',
+    path => '',
+    method => 'GET',
+    description => 'Directory index.',
+    permissions => {
+        user => 'all',
+    },
+    parameters => {
+        additionalProperties => 0,
+        properties => {},
+    },
+    returns => {
+        type => 'array',
+        items => {
+            type => "object",
+            additionalProperties => 0,
+            properties => {
+                subdir => {
+                    type => 'string',
+                },
+            },
+        },
+        links => [{ rel => 'child', href => "{subdir}" }],
+    },
+    code => sub($param) {
+        my $result = [];
+
+        my $attrs = __PACKAGE__->method_attributes();
+
+        for my $info ($attrs->@*) {
+            next if !$info->{subclass};
+
+            push $result->@*, { subdir => $info->{match_re}->[0] };
+        }
+
+        return $result;
+    },
+});
+
+1;
diff --git a/src/PVE/API2/Plugins/Storage/Makefile b/src/PVE/API2/Plugins/Storage/Makefile
new file mode 100644
index 00000000..06473a2f
--- /dev/null
+++ b/src/PVE/API2/Plugins/Storage/Makefile
@@ -0,0 +1,17 @@
+SOURCES = Plugin.pm		\
+
+
+SUBDIRS =
+
+
+INSTALL_PATH = ${DESTDIR}${PERLDIR}/PVE/API2/Plugins/Storage
+
+.PHONY: install
+install:
+	set -e && for SOURCE in ${SOURCES}; \
+		do install -D -m 0644 $$SOURCE ${INSTALL_PATH}/$$SOURCE; \
+	done
+	set -e && for SUBDIR in ${SUBDIRS}; \
+		do make -C $$SUBDIR install; \
+	done
+
diff --git a/src/PVE/API2/Plugins/Storage/Plugin.pm b/src/PVE/API2/Plugins/Storage/Plugin.pm
new file mode 100644
index 00000000..4e98b6b5
--- /dev/null
+++ b/src/PVE/API2/Plugins/Storage/Plugin.pm
@@ -0,0 +1,128 @@
+package PVE::API2::Plugins::Storage::Plugin;
+
+use v5.36;
+
+use Storable qw(dclone);
+
+use PVE::Exception qw(raise);
+use PVE::RESTHandler;
+use PVE::Storage; # pre-load plugins
+use PVE::Storage::Plugin;
+use PVE::Tools qw(extract_param);
+
+use base qw(PVE::RESTHandler);
+
+my $ALL_PLUGIN_TYPES = PVE::Storage::Plugin->lookup_types();
+
+my $PLUGIN_ORIGINS = ['builtin', 'custom'];
+
+my sub plugin_origin($plugin) {
+    return $plugin =~ m/^PVE::Storage::Custom::/ ? 'custom' : 'builtin';
+}
+
+my $PLUGIN_METADATA_SCHEMA = {
+    type => 'object',
+    additionalProperties => 0,
+    properties => {
+        origin => {
+            description => "Whether the plugin is shipped with Proxmox VE ('builtin') or"
+                . " installed separately ('custom').",
+            type => 'string',
+            enum => $PLUGIN_ORIGINS,
+            optional => 0,
+        },
+        type => {
+            description => "The storage type of the plugin.",
+            type => 'string',
+            optional => 0,
+            enum => $ALL_PLUGIN_TYPES,
+        },
+    },
+};
+
+# plugins/storage/plugin
+
+__PACKAGE__->register_method({
+    name => 'index',
+    path => '',
+    method => 'GET',
+    description => 'List all available storage plugins and their metadata.',
+    permissions => {
+        user => 'all',
+    },
+    parameters => {
+        additionalProperties => 0,
+        properties => {
+            origin => {
+                description => "Only list plugins of this origin.",
+                type => 'string',
+                enum => $PLUGIN_ORIGINS,
+                optional => 1,
+            },
+        },
+    },
+    returns => {
+        type => 'array',
+        items => $PLUGIN_METADATA_SCHEMA,
+        links => [{ rel => 'child', href => '{type}' }],
+    },
+    code => sub($param) {
+        my $origin = extract_param($param, 'origin');
+
+        my $result = [];
+
+        for my $type ($ALL_PLUGIN_TYPES->@*) {
+            if (defined($origin)) {
+                my $plugin = PVE::Storage::Plugin->lookup($type);
+                next if plugin_origin($plugin) ne $origin;
+            }
+
+            my $item = {
+                origin => $origin,
+                type => $type,
+            };
+
+            push($result->@*, $item);
+        }
+
+        return $result;
+    },
+});
+
+# plugins/storage/plugin/{type}
+
+__PACKAGE__->register_method({
+    name => 'info',
+    path => '{type}',
+    method => 'GET',
+    description => 'Fetch metadata of a storage plugin.',
+    permissions => {
+        user => 'all',
+    },
+    parameters => {
+        additionalProperties => 0,
+        properties => {
+            type => {
+                description => 'The type of the storage plugin.',
+                type => 'string',
+                enum => $ALL_PLUGIN_TYPES,
+            },
+        },
+    },
+    returns => $PLUGIN_METADATA_SCHEMA,
+    code => sub($param) {
+        my $param_type = extract_param($param, 'type');
+
+        # Does not fail since `type` is validated first
+        my $plugin = PVE::Storage::Plugin->lookup($param_type);
+
+        my $result = {
+            origin => plugin_origin($plugin),
+            type => $param_type,
+        };
+
+        return $result;
+    },
+});
+
+1;
-- 
2.47.3





  parent reply	other threads:[~2026-11-13 20:34 UTC|newest]

Thread overview: 22+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2026-11-13 20:33 [PATCH common/manager/proxmox-widget-toolkit/storage/storage-plugin-examples v5 00/19] GUI Support for Custom Storage Plugins Max R. Carrara
2026-11-13 20:33 ` [PATCH pve-common v5 01/19] json schema: add multiline validation keyword Max R. Carrara
2026-11-13 20:33 ` Max R. Carrara [this message]
2026-11-13 20:33 ` [PATCH pve-storage v5 03/19] api: plugins/storage/plugin: include schema in plugin metadata Max R. Carrara
2026-11-13 20:33 ` [PATCH pve-storage v5 04/19] api: plugins/storage/plugin: handle sensitive properties in schema Max R. Carrara
2026-11-13 20:33 ` [PATCH pve-storage v5 05/19] api: plugins/storage/plugin: factor plugin metadata code into helper Max R. Carrara
2026-11-13 20:33 ` [PATCH pve-storage v5 06/19] api: plugins/storage/plugin: add plugins' 'content' to their metadata Max R. Carrara
2026-11-13 20:33 ` [PATCH pve-storage v5 07/19] all plugins: add 'title' to properties, adapt 'description's Max R. Carrara
2026-11-13 20:33 ` [PATCH pve-storage v5 08/19] all plugins, api: mark certain properties as advanced in plugindata() Max R. Carrara
2026-11-13 20:33 ` [PATCH pve-storage v5 09/19] all plugins, api: mark certain properties as hidden " Max R. Carrara
2026-11-13 20:33 ` [PATCH pve-storage v5 10/19] api: plugins/storage/plugin: allow plugins to have display names Max R. Carrara
2026-11-13 20:33 ` [PATCH proxmox-widget-toolkit v5 11/19] form: introduce new 'proxmoxtextarea' field Max R. Carrara
2026-11-13 20:33 ` [PATCH proxmox-widget-toolkit v5 12/19] utils: introduce helper function getFieldDefFromPropertySchema Max R. Carrara
2026-11-13 20:33 ` [PATCH proxmox-widget-toolkit v5 13/19] acme: use helper to construct ExtJS fields from property schemas Max R. Carrara
2026-11-13 20:33 ` [PATCH pve-manager v5 14/19] api: sort modules and API method registrations Max R. Carrara
2026-11-13 20:33 ` [PATCH pve-manager v5 15/19] ui: storage: remove entry of the removed DRBD plugin Max R. Carrara
2026-11-13 20:33 ` [PATCH pve-manager v5 16/19] api: add API routes 'plugins' and 'plugins/storage' Max R. Carrara
2026-11-13 20:33 ` [PATCH pve-manager v5 17/19] ui: storage view: display error when no editor for storage type exists Max R. Carrara
2026-11-13 20:33 ` [PATCH pve-manager v5 18/19] ui: storage: add basic UI integration for custom storage plugins Max R. Carrara
2026-11-13 20:33 ` [PATCH pve-storage-plugin-examples v5 19/19] sshfs: Update SSHFS plugin Max R. Carrara
2026-11-16  2:20 ` applied: [PATCH common/manager/proxmox-widget-toolkit/storage/storage-plugin-examples v5 00/19] GUI Support for Custom Storage Plugins Thomas Lamprecht
2026-11-17  8:07 ` Roland Kammerer

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20261113203330.932813-3-m.carrara@proxmox.com \
    --to=m.carrara@proxmox.com \
    --cc=gerencia@idkmanager.com \
    --cc=j.klocker@proxmox.com \
    --cc=pve-devel@lists.proxmox.com \
    --cc=t.ellmenreich@proxmox.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox
Service provided by Proxmox Server Solutions GmbH | Privacy | Legal