From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from gate001.proxmox.com (gate001.proxmox.com [45.144.208.40]) by lore.proxmox.com (Postfix) with ESMTPS id F27291FF0C0 for ; Wed, 18 Nov 2026 10:15:17 +0100 (CET) Received: from gate001.proxmox.com (localhost.localdomain [127.0.0.1]) by gate001.proxmox.com (Proxmox) with ESMTP id 9CDA121728; Wed, 18 Nov 2026 10:14:49 +0100 (CET) From: "Max R. Carrara" To: pve-devel@lists.proxmox.com Subject: [PATCH pve-storage v3 50/51] bump the storage plugin API version Date: Wed, 18 Nov 2026 10:14:12 +0100 Message-ID: <20261118091416.27183-6-m.carrara@proxmox.com> X-Mailer: git-send-email 2.47.3 In-Reply-To: <20261118091416.27183-1-m.carrara@proxmox.com> References: <20261117203953.913035-1-m.carrara@proxmox.com> <20261118091416.27183-1-m.carrara@proxmox.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Bm-Milter-Handled: 55990f41-d878-4baa-be0a-ee34c49e34d2 X-Bm-Transport-Timestamp: 1794993267484 X-SPAM-LEVEL: Spam detection results: 0 AWL 0.232 Adjusted score from AWL reputation of From: address DMARC_MISSING 0.1 Missing DMARC policy KAM_DMARC_STATUS 0.01 Test Rule for DKIM or SPF Failure with Strict Alignment (newer systems) KAM_SHORT 0.001 Use of a URL Shortener for very short URL RCVD_IN_DNSWL_MED -2.3 Sender listed at https://www.dnswl.org/, medium trust SPF_HELO_NONE 0.001 SPF: HELO does not publish an SPF Record SPF_PASS -0.001 SPF: sender matches SPF record Message-ID-Hash: VDQ7XMBV3ZOZKCGY5FSXC6Z3PFA74IP5 X-Message-ID-Hash: VDQ7XMBV3ZOZKCGY5FSXC6Z3PFA74IP5 X-MailFrom: m.carrara@proxmox.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; loop; banned-address; emergency; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header CC: Wolfgang Bumiller X-Mailman-Version: 3.3.10 Precedence: list List-Id: Proxmox VE development discussion List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: Signed-off-by: Max R. Carrara --- 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