From: "Max R. Carrara" <m.carrara@proxmox.com>
To: pve-devel@lists.proxmox.com
Cc: Wolfgang Bumiller <w.bumiller@proxmox.com>
Subject: [PATCH pve-storage v3 50/51] bump the storage plugin API version
Date: Wed, 18 Nov 2026 10:14:12 +0100 [thread overview]
Message-ID: <20261118091416.27183-6-m.carrara@proxmox.com> (raw)
In-Reply-To: <20261118091416.27183-1-m.carrara@proxmox.com>
Signed-off-by: Max R. Carrara <m.carrara@proxmox.com>
---
ApiChangeLog | 77 ++++++++++++++++++++++++++++++++++++++++++++++
src/PVE/Storage.pm | 4 +--
2 files changed, 79 insertions(+), 2 deletions(-)
diff --git a/ApiChangeLog b/ApiChangeLog
index 0887c308..fbab3c72 100644
--- a/ApiChangeLog
+++ b/ApiChangeLog
@@ -4,10 +4,87 @@ Our API versioning contains an `APIVER` and an `APIAGE`.
The `APIAGE` is the number of versions we're backward compatible with. (iow. things got added
without breaking anything unaware of it.)
Future changes should be documented in here.
+## Version 18:
+
+* Volume names of the `iso`, `vztmpl` and `snippets` volume types may contain subdirectories
+
+ Their files can be placed in subdirectories of the content directory, up to the
+ depth set by the new `max-scan-depth` storage property. Code that takes the
+ part after the volume type prefix of such volume names as a plain file name
+ needs to account for this.
+
+* Deprecate the following regular expressions:
+ * `$PVE::Storage::ISO_EXT_RE_0` (`iso` volume type)
+ * `$PVE::Storage::VZTMPL_EXT_RE_1` (`vztmpl` volume type)
+ * `$PVE::Storage::BACKUP_EXT_RE_2` (`backup` volume type)
+ * `$PVE::Storage::IMPORT_EXT_RE_1` (`import` volume type)
+ * `$PVE::Storage::UPLOAD_IMPORT_EXT_RE_1` (`import` volume type)
+ * `$PVE::Storage::OVA_CONTENT_RE_1` (`import` volume type)
+
+ These regular expressions were mostly used for parsing file paths and volume
+ names corresponding to their volume types, noted in parentheses above. They
+ are no longer used within pve-storage and will be removed on the next APIAGE
+ reset.
+
+ Instead, the parsing functions in `PVE::Storage::Common::Parse` should be
+ used.
+
+ * Deprecate the `PVE::Storage::Plugin::COMPRESSOR_RE` constant
+
+ It is only used by `$PVE::Storage::BACKUP_EXT_RE_2` and will be removed
+ together with it on the next APIAGE reset.
+
+* Migrate the following regular expressions:
+ * `$PVE::Storage::SAFE_CHAR_CLASS_RE`
+ * `$PVE::Storage::SAFE_CHAR_WITH_WHITESPACE_CLASS_RE`
+
+ These regular expressions are now defined as private constants in the
+ `PVE::Storage::Common::Parse` module and can be obtained by using the
+ corresponding subroutines in the *STANDALONE REGULAR EXPRESSIONS* section in
+ said module. The variables in `PVE::Storage` remain until the next APIAGE
+ reset.
+
+* Replace plugin helper `get_vtype_subdirs()` with standalone helper subroutine
+ `PVE::Storage::Common::plugin_get_default_vtype_subdirs()`
+
+ The `get_vtype_subdirs()` subroutine in `PVE::Storage::Plugin` was an
+ internal helper with a public signature, and was never meant to be
+ overridden.
+
+ Therefore, it is replaced with the `plugin_get_default_vtype_subdirs()`
+ subroutine from `PVE::Storage::Common` in order to make this distinction
+ clearer.
+
+ In order to make it clear that this is a helper and not meant to be part of
+ the storage plugin API, it is replaced with the more explicit
+ `PVE::Storage::Common::plugin_get_default_vtype_subdirs()` subroutine.
+
+* Replace plugin method `get_subdir()` with standalone helper subroutine
+ `PVE::Storage::Common::plugin_get_vtype_subdir()`
+
+ The `get_subdir()` method in `PVE::Storage::Plugin` was an internal helper
+ method with a public signature. Moreover, its signature could mistakenly
+ suggest that this method was part of the storage plugin API, which it was not
+ originally meant to be.
+
+ In order to make it clear that this is just a helper, it is replaced with the
+ more explicit `PVE::Storage::Common::plugin_get_vtype_subdir()` subroutine.
+
+ Both `get_vtype_subdirs()` and `get_subdir()` remain as wrappers until the
+ next APIAGE reset. Plugin authors are encouraged to switch to the new helper
+ subroutines as soon as possible.
+
+* `list_volumes()` of `PVE::Storage::Plugin` only returns volumes of content
+types that the storage configuration declares
+
+ `PVE::Storage::volume_list()` already filtered the requested content types
+ like this, so only plugins and code calling `list_volumes()` directly are
+ affected.
+
## Version 17:
* Add the volume types `vm-vol`, `vm-state` and `ct-vol`
A guest volume can now have a more specific type than `images`: `vm-vol` for a volume that a VM
diff --git a/src/PVE/Storage.pm b/src/PVE/Storage.pm
index 3cd17993..b451f872 100755
--- a/src/PVE/Storage.pm
+++ b/src/PVE/Storage.pm
@@ -56,15 +56,15 @@ use PVE::Storage::ZFSPlugin;
use PVE::Storage::PBSPlugin;
use PVE::Storage::BTRFSPlugin;
use PVE::Storage::ESXiPlugin;
# Storage API version. Increment it on changes in storage API interface.
-use constant APIVER => 17;
+use constant APIVER => 18;
# Age is the number of versions we're backward compatible with.
# This is like having 'current=APIVER' and age='APIAGE' in libtool,
# see https://www.gnu.org/software/libtool/manual/html_node/Libtool-versioning.html
-use constant APIAGE => 8;
+use constant APIAGE => 9;
our $KNOWN_EXPORT_FORMATS = ['raw+size', 'tar+size', 'qcow2+size', 'vmdk+size', 'zfs', 'btrfs'];
# load standard plugins
PVE::Storage::DirPlugin->register();
--
2.47.3
next prev parent reply other threads:[~2026-11-18 9:15 UTC|newest]
Thread overview: 52+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-11-17 20:38 [PATCH manager/storage v3 00/51] Fix #2884: Implement Subdirectory Scanning for Dir-Based Storage Types Max R. Carrara
2026-11-17 20:38 ` [PATCH pve-storage v3 01/51] test: plugin tests: run tests with at most 4 jobs Max R. Carrara
2026-11-17 20:38 ` [PATCH pve-storage v3 02/51] plugin, common: remove superfluous use of =pod command paragraph Max R. Carrara
2026-11-17 20:38 ` [PATCH pve-storage v3 03/51] common: use Exporter module for PVE::Storage::Common Max R. Carrara
2026-11-17 20:38 ` [PATCH pve-storage v3 04/51] plugin: make get_subdir_files a proper subroutine and update style Max R. Carrara
2026-11-17 20:38 ` [PATCH pve-storage v3 05/51] plugin api: replace subdir helper methods with standalone functions Max R. Carrara
2026-11-17 20:38 ` [PATCH pve-storage v3 06/51] common: prevent autovivification in plugin_get_vtype_subdir helper Max R. Carrara
2026-11-17 20:38 ` [PATCH pve-storage v3 07/51] plugin: break up if-elsif chain into separate if-blocks Max R. Carrara
2026-11-17 20:38 ` [PATCH pve-storage v3 08/51] plugin: adapt get_subdir_files helper of list_volumes API method Max R. Carrara
2026-11-17 20:38 ` [PATCH pve-storage v3 09/51] plugin: update code style of list_volumes plugin " Max R. Carrara
2026-11-17 20:38 ` [PATCH pve-storage v3 10/51] plugin: use closure for obtaining raw volume data in list_volumes Max R. Carrara
2026-11-17 20:38 ` [PATCH pve-storage v3 11/51] plugin: use closure for inner loop logic " Max R. Carrara
2026-11-17 20:38 ` [PATCH pve-storage v3 12/51] storage: update code style in function path_to_volume_id Max R. Carrara
2026-11-17 20:38 ` [PATCH pve-storage v3 13/51] storage: break up if-elsif chain in path_to_volume_id Max R. Carrara
2026-11-17 20:38 ` [PATCH pve-storage v3 14/51] storage: heave vtype file path parsing logic inside loop into helper Max R. Carrara
2026-11-17 20:38 ` [PATCH pve-storage v3 15/51] storage: clean up code that was moved into helper in path_to_volume_id Max R. Carrara
2026-11-17 20:38 ` [PATCH pve-storage v3 16/51] api: status: move content type assert for up-/downloads into helper Max R. Carrara
2026-11-17 20:38 ` [PATCH pve-storage v3 17/51] api: status: use get_subdir helper method to get content directory Max R. Carrara
2026-11-17 20:38 ` [PATCH pve-storage v3 18/51] api: status: move up-/download file path parsing code into helper Max R. Carrara
2026-11-17 20:38 ` [PATCH pve-storage v3 19/51] api: status: simplify file content assertion logic for up-/download Max R. Carrara
2026-11-17 20:38 ` [PATCH pve-storage v3 20/51] test: guest import: add tests for PVE::GuestImport Max R. Carrara
2026-11-17 20:38 ` [PATCH pve-storage v3 21/51] tree-wide: introduce parsing module and replace usages of ISO_EXT_RE_0 Max R. Carrara
2026-11-17 20:38 ` [PATCH pve-storage v3 22/51] common: test: set up parser testing code, add tests for 'iso' vtype Max R. Carrara
2026-11-17 20:38 ` [PATCH pve-storage v3 23/51] tree-wide: replace usages of VZTMPL_EXT_RE_1 with parsing functions Max R. Carrara
2026-11-17 20:38 ` [PATCH pve-storage v3 24/51] tree-wide: replace usages of BACKUP_EXT_RE_2 " Max R. Carrara
2026-11-17 20:38 ` [PATCH pve-storage v3 25/51] tree-wide: replace usages of inline regexes for snippets with parsers Max R. Carrara
2026-11-17 20:38 ` [PATCH pve-storage v3 26/51] tree-wide: partially replace usages of regexes for 'import' vtype Max R. Carrara
2026-11-17 20:38 ` [PATCH pve-storage v3 27/51] tree-wide: replace remaining " Max R. Carrara
2026-11-17 20:39 ` [PATCH pve-storage v3 28/51] tree-wide: simplify recently refactored parsing logic Max R. Carrara
2026-11-17 20:39 ` [PATCH pve-storage v3 29/51] test: list volumes: reorganize and modernize test running code Max R. Carrara
2026-11-17 20:39 ` [PATCH pve-storage v3 30/51] test: list volumes: fix broken test checking for vmlist modifications Max R. Carrara
2026-11-17 20:39 ` [PATCH pve-storage v3 31/51] test: list volumes: introduce new format for test cases Max R. Carrara
2026-11-17 20:39 ` [PATCH pve-storage v3 32/51] test: list volumes: remove legacy code and migrate cases to new format Max R. Carrara
2026-11-17 20:39 ` [PATCH pve-storage v3 33/51] plugin: do not return volumes of undeclared content types anymore Max R. Carrara
2026-11-17 20:39 ` [PATCH pve-storage v3 34/51] plugin: correct comment in get_subdir_files helper Max R. Carrara
2026-11-17 20:39 ` [PATCH pve-storage v3 35/51] test: parse volname: modernize code Max R. Carrara
2026-11-17 20:39 ` [PATCH pve-storage v3 36/51] test: parse volname: adapt tests regarding 'import' volume type Max R. Carrara
2026-11-17 20:39 ` [PATCH pve-storage v3 37/51] test: parse volname: move VM disk test creation into separate block Max R. Carrara
2026-11-17 20:39 ` [PATCH pve-storage v3 38/51] test: parse volname: move backup file test creation into sep. block Max R. Carrara
2026-11-17 20:39 ` [PATCH pve-storage v3 39/51] test: parse volname: parameterize test case creation for some vtypes Max R. Carrara
2026-11-17 20:39 ` [PATCH pve-storage v3 40/51] test: volume id: modernize code Max R. Carrara
2026-11-17 20:39 ` [PATCH pve-storage v3 41/51] test: volume id: rename 'volname' test case parameter to 'file' Max R. Carrara
2026-11-17 20:39 ` [PATCH pve-storage v3 42/51] test: filesystem path: modernize code Max R. Carrara
2026-11-17 20:39 ` [PATCH pve-storage v3 43/51] plugin: list content directories without globbing Max R. Carrara
2026-11-18 9:12 ` [PATCH pve-storage v3 44/51] fix #2884: implement nested subdir scanning and support 'iso' vtype Max R. Carrara
2026-11-18 9:14 ` [PATCH pve-storage v3 45/51] fix #2884: support nested subdir scanning for 'vztmpl' volume type Max R. Carrara
2026-11-18 9:14 ` [PATCH pve-storage v3 46/51] fix #2884: support nested subdir scanning for 'snippets' vtype Max R. Carrara
2026-11-18 9:14 ` [PATCH pve-storage v3 47/51] test: add more tests for 'import' vtype & guard against nested subdirs Max R. Carrara
2026-11-18 9:14 ` [PATCH pve-storage v3 48/51] test: add tests guarding against subdir scanning for vtypes Max R. Carrara
2026-11-18 9:14 ` [PATCH pve-storage v3 49/51] storage: resolve images in content dir overrides ending with a slash Max R. Carrara
2026-11-18 9:14 ` Max R. Carrara [this message]
2026-11-18 9:14 ` [PATCH pve-manager v3 51/51] fix #2884: ui: storage: add field for 'max-scan-depth' property Max R. Carrara
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=20261118091416.27183-6-m.carrara@proxmox.com \
--to=m.carrara@proxmox.com \
--cc=pve-devel@lists.proxmox.com \
--cc=w.bumiller@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