feat(blob): optional blob event capture to files (Event Grid schema)

[The3G]

Summary

Adds an opt-in feature that captures mutating blob operations as Azure Event Grid–schema JSON files on disk, so they can be processed later by external tooling. Controlled entirely by a command-line / configuration switch and off by default.

• New --blobEventCapture boolean flag (off by default) plus optional --blobEventCapturePath <dir> (defaults to <location>/__blobevents__); mirrored by VS Code settings azurite.blobEventCapture / azurite.blobEventCapturePath.
• Captures all mutating blob/container operations (container create/delete, put/delete blob, put block list, page/append writes, …), emitting one JSON file per event named ${eventTime}-${id}.json using the Event Grid storage event schema (eventType, subject, data.api, data.url, data.eTag, data.contentLength, data.blobType, sequencer, …).
• Writes are fire-and-forget and never fail a storage operation; the sink self-disables if it cannot initialize (mirrors the existing Telemetry precedent).
• Wired through both backends (LokiJS BlobServer and SqlBlobServer) and both entry points (CLI BlobServerFactory and the VS Code extension).

Implementation notes

• Event files are published atomically (write <name>.json.tmp then rename()), so consumers never observe a partially written file.
• The captured data.url has its query string stripped, so SAS credentials are never persisted to disk.
• Event filename segments are sanitized to prevent path traversal.

Test plan

• npm run test:blob (LokiJS suite): 543 passing, 0 failing, 3 pending
• New unit tests: BlobEventFactory (schema + SAS stripping), FileBlobEventSink (atomic write + self-disable), resolveBlobEventCapturePath
• New end-to-end test tests/blob/apis/eventCapture.test.ts: container create/delete, put/delete blob, put block + block list, and disabled-by-default (folder never created)
• npx eslint src/**/*.ts: clean
• README updated with the new CLI flags and VS Code settings

Notes

The feature is entirely off unless explicitly enabled, so existing behaviour is unchanged by default. Configuring a capture path without enabling capture is a no-op (a warning is logged and the path is ignored).

[Copilot]

Pull request overview

Adds an opt-in “blob event capture” feature that records mutating blob/container operations as Azure Event Grid–schema JSON files on disk, wired through both CLI and VS Code entry points and both LokiJS/SQL backends.

Changes:

• Introduces Event Grid–shaped blob event model + factory and a file-based sink with atomic publish semantics.
• Plumbs an optional event sink through the blob request pipeline and emits events from mutating handlers.
• Adds unit/E2E tests plus CLI/VS Code configuration surface and documentation updates.

Reviewed changes

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

Show a summary per file

File	Description
tests/BlobTestServerFactory.ts	Extends test server factory to enable/route blob event capture in tests.
tests/blob/resolveBlobEventCapturePath.test.ts	Unit tests for capture-path resolution behavior.
tests/blob/FileBlobEventSink.test.ts	Unit tests for file sink atomic writes, filename safety, and self-disable.
tests/blob/BlobEventFactory.test.ts	Unit tests for event envelope/schema, SAS query stripping, and sequencer behavior.
tests/blob/apis/eventCapture.test.ts	E2E coverage validating events are written when enabled and not written by default.
src/common/VSCServerManagerBlob.ts	Wires VS Code settings into blob server configuration for event capture.
src/common/VSCEnvironment.ts	Adds VS Code settings accessors for blob event capture flags/path.
src/common/Environment.ts	Adds CLI flags for blob event capture and capture path.
src/blob/utils/constants.ts	Adds default __blobevents__ folder constant.
src/blob/SqlBlobServer.ts	Creates/initializes/closes the optional file event sink in SQL backend.
src/blob/SqlBlobConfiguration.ts	Extends SQL config to carry capture enable/path settings.
src/blob/IBlobEnvironment.ts	Adds environment interface accessors for capture enable/path.
src/blob/handlers/PageBlobHandler.ts	Emits events for page blob create/page writes; plumbs sink into handler base.
src/blob/handlers/ContainerHandler.ts	Emits container create/delete events; plumbs sink into handler base.
src/blob/handlers/BlockBlobHandler.ts	Emits events for PutBlob/PutBlock/PutBlockList operations.
src/blob/handlers/BlobHandler.ts	Emits blob delete events; plumbs sink into handler base.
src/blob/handlers/BaseHandler.ts	Adds common emitBlobEvent() helper to safely publish events.
src/blob/handlers/AppendBlobHandler.ts	Emits events for append blob create/append writes.
src/blob/events/resolveBlobEventCapturePath.ts	Shared logic to resolve effective capture path for CLI + VS Code.
src/blob/events/IBlobEventSink.ts	Defines sink interface (init/emit/close) with non-throwing contract.
src/blob/events/IBlobEvent.ts	Defines Event Grid–shaped event types and payload structure.
src/blob/events/FileBlobEventSink.ts	Implements file sink with sanitization + temp-write + rename publish.
src/blob/events/BlobEventFactory.ts	Builds Event Grid–shaped events and strips SAS query strings from URLs.
src/blob/BlobServerFactory.ts	Wires CLI flags into blob configuration; resolves default capture path and warns on misconfig.
src/blob/BlobServer.ts	Creates/initializes/closes the optional file event sink in LokiJS backend.
src/blob/BlobRequestListenerFactory.ts	Plumbs the optional sink into handler construction.
src/blob/BlobEnvironment.ts	Adds blob-specific CLI flags accessors for capture enable/path.
src/blob/BlobConfiguration.ts	Extends blob config to carry capture enable/path settings.
README.md	Documents new CLI flags and VS Code settings and the on-disk schema/behavior.
package.json	Adds VS Code extension settings azurite.blobEventCapture and azurite.blobEventCapturePath.

Suppressed comments (1)

src/blob/BlobRequestListenerFactory.ts:122

• ServiceHandler is created without the eventSink, so ServiceSubmitBatch (which delegates to BlobBatchHandler) will not emit captured events even when blob event capture is enabled. This breaks the stated goal of capturing mutating blob operations, since batch sub-requests can include create/delete/put operations.

      serviceHandler: new ServiceHandler(
        this.accountDataStore,
        this.oauth,
        this.metadataStore,
        this.extentStore,

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 30 out of 30 changed files in this pull request and generated no new comments.

Suppressed comments (1)

src/blob/events/BlobEventFactory.ts:17

• sequencerCounter is a number, so after ~9e15 events it will lose integer precision and nextSequencer() can stop being strictly monotonic. Since sequencer is intended to reflect ordering, using bigint avoids precision loss in long-running/high-throughput scenarios.

let sequencerCounter = 0;
function nextSequencer(): string {
  sequencerCounter += 1;
  return sequencerCounter.toString(16).padStart(64, "0");
}

[The3G]

@microsoft-github-policy-service agree