feat(blob): blob versioning support, opt-in per storage account (#665)

[Gavin Thompson (gavin-thompson-postman)]

Summary

Implements blob versioning for the LokiJS metadata store, opt-in per storage account and off by default. Fixes #665.

• Versioning is an ARM management plane setting in Azure Storage (Microsoft.Storage/storageAccounts/blobServices/default#isVersioningEnabled), not part of the data plane REST API Azurite emulates — Set Blob Service Properties has no Versioning element. Since Azurite has no management plane, the setting is supplied at start up via two mutually exclusive options, --accountConfigFile <path> and --accountConfig <json>, mirrored by VS Code settings azurite.accountConfigFile / azurite.accountConfig. Multiple accounts are supported; an account that is not listed keeps the defaults, so this only ever opts accounts in.
• No generated artifacts are edited. The existing swagger already defines the versionid query parameter on 15 operations and VersionId / IsCurrentVersion / HasVersionsOnly on BlobItemInternal, so the wire contract needed no codegen changes.
• Version-creating operations follow the observed service behaviour: Put Blob, Put Block List, Copy Blob, Set Blob Metadata, Page/Append Blob Create, and Snapshot Blob create versions and return x-ms-version-id. Put Page and Append Block correctly do not.
• Reads and deletes accept ?versionid=; x-ms-is-current-version is returned only for the current version. List Blobs supports include=versions. Tags and access tier are addressable per version. A version is restored by copying it over the current version.
• Delete Blob without a version ID turns the current version into a previous version and retains it. Deleting the current version by ID is refused with 403 OperationNotAllowedOnRootBlob, matching the service.
• Versioning can be turned on and off against an existing workspace, as on a real account. Turning it off keeps existing versions listed, readable and deletable by version ID.
• Account configuration lives in a standalone src/common/account/ module with its own database file, so the queue and table services can share it rather than reading data owned by the blob service.

Implementation notes

• Previous versions share the base blob's snapshot value in the blobs collection, so every lookup meaning "the blob itself" excludes them. Blobs written before versioning was enabled have no isCurrentVersion field, so those queries match isCurrentVersion !== false and keep resolving unchanged. versionId is part of the collection index, and ensureIndex runs for workspaces created before versioning existed.
• Retention is a property of the document, not of the account setting: an existing current blob is demoted to a previous version whenever it is itself a version, and removed outright only when it is not. That one rule covers Put Blob, Put Block List, Copy Blob and Delete Blob, and is why turning versioning off does not destroy history.
• List continuation tokens now carry a secondary key, because every version of a blob shares its name — resuming from a name alone skipped the remaining versions of the blob a page stopped inside. Tokens without a secondary key keep the historical plain-blob-name format, so listings that do not involve versions are unchanged and tokens issued by earlier versions of Azurite remain valid.
• Version IDs match the service format (RFC 3339, 7-digit fractional seconds) and are generated with a single query for the newest existing version rather than probing candidate values.
• Loose mode ignores a malformed or mutually exclusive versionid and serves the current version, rather than rejecting it — versionid was ignored entirely before versioning existed, so loose mode does not become stricter.
• Versioning is not implemented for the SQL metadata store: configuring it with AZURITE_DB fails at start up, and a versionid request returns a not-implemented error rather than silently reading the current version.

Test plan

• Full LokiJS suite: 920 passing, 4 pending (--grep @loki)
• npm run test:upgrade (upgrade/persistence compatibility): 10 passing
• --inMemoryPersistence mode: versioning suite passes, no database file written
• npx eslint src/**/*.ts: clean
• New suites: blob.versioning.test.ts, blob.versioning.hierarchy.test.ts (delimiter × versions, including page size 1 and a blob whose name is also another blob's prefix), blob.versioning.toggle.test.ts, tests/common/AccountModel.test.ts, tests/common/LokiAccountModelStore.test.ts
• README updated with the new CLI flags and VS Code settings, Blob Versions moved out of the unsupported list, and a design doc added at docs/designs/blob-versioning.md
• ChangeLog updated in Upcoming Release

Verified against a real storage account

The versioning suites run unchanged against real Azure via the existing AZURITE_LIVE_TEST_CONNECTION_STRING live mode (33 passing against a GPv2 account with versioning enabled; the versioning-disabled and loose-mode suites are skipped there). Setup is documented in the design doc.

This found four places where the implementation had followed the prose documentation but the service behaves differently, all now following the observed behaviour:

	Documentation implies	Service does
Set Blob Properties	creates a version (every block blob write except Put Block)	creates no version, returns no x-ms-version-id
Delete current version by ID	permitted	403 OperationNotAllowedOnRootBlob
?snapshot= + ?versionid=	—	400 MutuallyExclusiveQueryParameters
HasVersionsOnly	—	not reported under include=versions, only include=deletedwithversions

Notes

• Existing behaviour is unchanged unless an account is explicitly configured with versioning enabled.
• One open design question for the maintainers. Enable Blob versioning #665 notes that how management plane configuration should reach Azurite is still undecided. --accountConfigFile / --accountConfig is one answer; if the team prefers a different mechanism, the surface is contained to src/common/account/, the three environment classes and BlobServerFactory, and can be swapped without touching the versioning logic. Happy to change it.
• The account configuration store lives in src/common/account/ so queue and table can share it, but the blob service owns its lifecycle for now as the only consumer. When another service reads it, ownership needs to move to the entry point and the instance be shared — two LokiJS instances autosaving one file would corrupt it. This is recorded on the field in BlobServer and in the design doc.
• Not implemented and out of scope, documented rather than partially emulated: blob version SAS (sr=bv and the x permission), soft-delete interactions, blob expiration, change feed, object replication, and versionid on Get Block List / Get Page Ranges (the swagger does not define it on either).

[Gavin Thompson (gavin-thompson-postman)]

@microsoft-github-policy-service agree company="Postman"

[Copilot]

Pull request overview

Adds opt-in Azure Blob versioning emulation to Azurite’s LokiJS metadata implementation (off by default), including request/response surface changes (versionid, x-ms-version-id, x-ms-is-current-version) and updated listing semantics/pagination to correctly handle multiple versions per blob name.

Changes:

• Introduces an account-level (management-plane-like) configuration model + Loki-backed store, wired into CLI and VS Code settings, to enable versioning per account.
• Extends Loki blob metadata behavior to create/read/list/delete versions, including updated continuation token encoding to resume within a blob’s versions.
• Adds extensive test coverage for versioning APIs, delimiter/hierarchy listing, loose mode behavior, and toggling versioning across restarts; updates docs/changelog.

Reviewed changes

Copilot reviewed 37 out of 37 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
tests/common/LokiAccountModelStore.test.ts	Unit coverage for account-config persistence/merge behavior in Loki store.
tests/common/AccountModel.test.ts	Unit coverage for parsing/validating account configuration and option resolution.
tests/BlobTestServerFactory.ts	Test server setup extended to inject account model/store and workspace suffixing.
tests/blob/pagewithdelimiter.test.ts	Adds token encoding/decoding and ordering tests for composite continuation markers.
tests/blob/apis/blob.versioning.toggle.test.ts	End-to-end tests for toggling versioning across restarts on same workspace.
tests/blob/apis/blob.versioning.test.ts	Main API suite covering version creation, reads, deletes, list behaviors, loose mode.
tests/blob/apis/blob.versioning.hierarchy.test.ts	Tests delimiter/hierarchy listing correctness with versions and pagination.
src/common/VSCEnvironment.ts	Adds VS Code settings support for account configuration (file/inline JSON).
src/common/utils/constants.ts	Defines default Loki DB path for the account configuration store.
src/common/IAccountModelEnvironment.ts	New environment interface for retrieving account model at startup.
src/common/EnvironmentFunctions.ts	Shared helper to resolve/validate --accountConfigFile / --accountConfig.
src/common/Environment.ts	Adds CLI flags for account configuration to the azurite entry point.
src/common/account/LokiAccountModelStore.ts	New LokiJS-backed persistence for per-account configuration.
src/common/account/index.ts	Barrel exports for account configuration module.
src/common/account/IAccountModelStore.ts	Contract for resolving and reading per-account configuration.
src/common/account/AccountModel.ts	Parsing/validation + types for account configuration, with defaults/errors.
src/blob/utils/utils.ts	Adds shared validation for snapshot + versionid query parameters.
src/blob/persistence/SqlBlobMetadataStore.ts	Explicitly rejects versioning requests against SQL metadata store.
src/blob/persistence/PageWithDelimiter.ts	Adds composite continuation token support (name + secondary key).
src/blob/persistence/LokiBlobMetadataStore.ts	Core Loki versioning logic: version IDs, retention, reads/lists/deletes/copies/tags/tier.
src/blob/persistence/IBlobMetadataStore.ts	Extends metadata-store interfaces to carry version/toggle/listing semantics.
src/blob/IBlobEnvironment.ts	Adds accountModel() to blob environment interface.
src/blob/handlers/PageBlobHandler.ts	Returns x-ms-version-id for page blob create when enabled.
src/blob/handlers/ContainerHandler.ts	Adds include=versions handling, plumbs includeVersions to metadata store.
src/blob/handlers/BlockBlobHandler.ts	Returns x-ms-version-id for block blob writes when enabled.
src/blob/handlers/BlobHandler.ts	Plumbs version resolution, adds version headers/behavior across operations.
src/blob/handlers/BaseHandler.ts	Centralizes strict vs loose validation/behavior for versionid + snapshot.
src/blob/handlers/AppendBlobHandler.ts	Returns x-ms-version-id for append blob create when enabled.
src/blob/errors/StorageErrorFactory.ts	Adds new errors for mutually exclusive params and root-blob restrictions.
src/blob/BlobServerFactory.ts	Initializes account config store and wires it into Blob server startup.
src/blob/BlobServer.ts	Owns lifecycle for the account config store (init/close/clean).
src/blob/BlobEnvironment.ts	Adds CLI flags for account config to azurite-blob entry point.
src/blob/BlobConfiguration.ts	Adds account model store handle to blob configuration.
README.md	Documents new CLI flags and VS Code settings; updates support matrix.
package.json	Adds VS Code extension configuration schema for new settings.
docs/designs/blob-versioning.md	Design doc describing model, behaviors, and non-goals.
ChangeLog.md	Upcoming release notes updated for new versioning feature.

Suppressed comments (1)

src/blob/persistence/PageWithDelimiter.ts:219

• PageWithDelimiter.add() enforces sorting by blob name only. With composite keys, passing items with the same name but a decreasing secondaryKey won’t throw, and can produce an incorrect continuation marker (skipping or duplicating results on resume).

    const [name, secondaryKey] = key;
    if (name < this.latestMarker[0]) {
      throw new Error("add received unsorted item. add must be called on sorted data");
    }

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 37 out of 37 changed files in this pull request and generated 1 comment.

Suppressed comments (2)

src/blob/persistence/PageWithDelimiter.ts:43

• encodePageMarker() returns the plain blob name when secondaryKey is empty. If a blob name itself starts with the composite marker prefix ("2!") and happens to be valid composite encoding, decodePageMarker() will misinterpret a historically-issued plain-name marker as composite and pagination can skip/duplicate items. Consider encoding names that start with the composite prefix even when there is no secondary key, to avoid collisions.

export function encodePageMarker(key: PageItemKey): string {
  const [name, secondaryKey] = key;
  if (secondaryKey === "") {
    return name;
  }

src/common/account/LokiAccountModelStore.ts:78

• LokiAccountModelStore.init() treats any fs.stat() error as "file doesn't exist" and proceeds. This can mask real problems (e.g., permission errors) and lead to confusing downstream failures. Only ignore ENOENT; reject other stat errors.

      stat(this.lokiDBPath, (statError) => {
        if (!statError) {
          this.db.loadDatabase({}, (dbError) => {
            if (dbError) {
              reject(dbError);
            } else {
              resolve();
            }
          });
        } else {
          // when the DB file doesn't exist, ignore the error because the following will
          // re-create the file
          resolve();
        }
      });