Winche.Storage.AspNetCore.Rest 10.0.0

There is a newer version of this package available.
See the version list below for details.
dotnet add package Winche.Storage.AspNetCore.Rest --version 10.0.0
                    
NuGet\Install-Package Winche.Storage.AspNetCore.Rest -Version 10.0.0
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Winche.Storage.AspNetCore.Rest" Version="10.0.0" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Winche.Storage.AspNetCore.Rest" Version="10.0.0" />
                    
Directory.Packages.props
<PackageReference Include="Winche.Storage.AspNetCore.Rest" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Winche.Storage.AspNetCore.Rest --version 10.0.0
                    
#r "nuget: Winche.Storage.AspNetCore.Rest, 10.0.0"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Winche.Storage.AspNetCore.Rest@10.0.0
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Winche.Storage.AspNetCore.Rest&version=10.0.0
                    
Install as a Cake Addin
#tool nuget:?package=Winche.Storage.AspNetCore.Rest&version=10.0.0
                    
Install as a Cake Tool

Winche.Storage

Lightweight .NET libraries for storing file metadata in PostgreSQL and bytes in an archive (S3-compatible, or a folder on disk) via signed URLs. The solution includes core abstractions, S3 and folder archive providers, an ASP.NET Core base + REST adapter, and a sample app.

Access control is enforced with Winche.Rules — the same rules engine used by Winche.Database.

Packages

Package Description
Winche.Storage Core: schema management, file CRUD, hooks, Winche.Rules guard
Winche.Storage.S3 S3-compatible archive provider (presigned URLs, multipart upload)
Winche.Storage.FileSystem A folder on disk (or a mounted volume) as the archive, through signed URLs your app serves (10.0.0)
Winche.Storage.AspNetCore ASP.NET Core base: MapClaims, a storage-specific override of the caller the host sets once for every Winche package (AddWincheCaller + UseWincheCaller, Winche.Core.AspNetCore)
Winche.Storage.AspNetCore.Rest Minimal-API REST endpoints (depends on the base package)

Architecture

Package dependencies:

flowchart TD
    Rest["Winche.Storage.AspNetCore.Rest<br/>MapWincheStorageRestApi"]
    Base["Winche.Storage.AspNetCore<br/>FileClaimsAccessor · MapClaims"]
    S3["Winche.Storage.S3<br/>UseS3Archive · S3Archive"]
    FS["Winche.Storage.FileSystem<br/>UseFileSystemArchive · FileSystemArchive"]
    Core["Winche.Storage<br/>IFileStorage · guard · schema · hooks"]
    Rules["Winche.Rules<br/>RuleEngine · RuleText"]

    Rest --> Base
    Rest --> Core
    Base --> Core
    S3 --> Core
    FS --> Core
    Core --> Rules

Runtime components inside the core. The public IFileStorage is the rules guard; it authorizes through the RuleEngine, then delegates to the unprotected FileStorage, which talks to Postgres and the pluggable archive:

flowchart LR
    IFM["IFileStorage"] --> Guard["RuleGuardedFileStorage"]
    Guard -->|authorize| Engine["RuleEngine"]
    Guard -->|delegate| Core["FileStorage"]
    Engine --> Claims["IRuleClaimsAccessor"]
    Core --> DB[("PostgreSQL")]
    Core --> Archive["IArchive<br/>NullArchive / S3Archive / FileSystemArchive"]

Install

dotnet add package Winche.Storage
dotnet add package Winche.Storage.S3            # or Winche.Storage.FileSystem
dotnet add package Winche.Storage.AspNetCore.Rest

Quick Start

1. Configure appsettings.json

{
  "ConnectionStrings": {
    "WincheStorage": "Host=localhost;Database=mydb;Username=user;Password=pass"
  },
  "WincheStorage:S3Archive": {
    "BucketName": "your-bucket",
    "RegionName": "us-east-1",
    "AccessKey": "YOUR_ACCESS_KEY",
    "SecretKey": "YOUR_SECRET_KEY",
    "PresignedUrlExpiry": "00:15:00"
  }
}

AccessKey and SecretKey are optional. Omit them when deploying to AWS with a task role or instance profile — the SDK uses ambient IAM credentials automatically.

For a non-public schema, add Search Path=myschema to the connection string (the metadata table is created in the connection's search_path).

2. Register services

using Winche.Rules;
using Winche.Rules.Expressions;
using Winche.Storage.AspNetCore.DependencyInjection;       // MapClaims
using Winche.Storage.DependencyInjection;                  // AddWincheStorage
using Winche.Storage.S3.DependencyInjection;               // UseS3Archive

builder.Services.AddWincheStorage(opts =>
{
    opts.ConnectionString = builder.Configuration.GetConnectionString("WincheStorage");

    // Default-deny. Grant access in the rules language (see Access Control).
    opts.UseRulesFile("storage.rules");

    opts.UseS3Archive(s3 => builder.Configuration.GetSection("WincheStorage:S3Archive").Bind(s3));

    // Map HTTP requests to caller claims consumed by the rules engine.
    opts.MapClaims(ctx => new Dictionary<string, object?>
    {
        ["userId"] = ctx.Request.Headers["X-USER-ID"].ToString(),
    });
});

3. Initialize schema and map endpoints

await app.InitializeWincheStorageAsync();   // creates the winche_files table if it doesn't exist
app.MapWincheStorageRestApi();              // maps REST routes under the "files/v1" prefix

See samples/Winche.Storage.Sample for a complete working example.

Configuration

AddWincheStorage

A single overload takes an Action<WincheStorageOptions>. Set the connection string and register components inside the lambda:

services.AddWincheStorage(opts =>
{
    opts.ConnectionString = "Host=...;Database=...;Username=...;Password=...";
    opts.UseRules(/* ... */);
    opts.UseHooks(h => h.Add<AuditHook>("userFiles/{userId}/{file=**}"));
    opts.UseS3Archive(/* Action<S3ArchiveOptions> */);
    opts.MapClaims(/* Func<HttpContext, IReadOnlyDictionary<string, object?>?> */);
});

WincheStorageOptions

Member Description
ConnectionString (required) Postgres connection string. Schema comes from its Search Path.
UseRulesFile(path) / UseRulesText(text) / UseRules(RuleSet) Adds rules to the guard. Multiple calls accumulate (OR-combined).
UseHooks(h => h.Add<T>(path)) Registers FileStoreHook lifecycle listeners, each bound to a path pattern.
UseOrphanSweep(...) Enables the background sweep that reclaims archive objects with no matching DB row. See Orphan Sweep.
MaxFileSizeBytes Largest file a client may register (null, the default: no limit beyond the archive's). Larger is invalid-argument (reason too-large); multipart parts that don't add up to the declared size are refused at confirm.
UseSettings() Lets the Winche console change the size limit, request logging and the orphan sweep without a deploy; code values are the starting ones. Needs AddWincheConfig(…).
LogRequests(...) Logs requests that go through the rules. See Request logging.
HookDelivery HookDeliveryOptions: poll interval, lease, retry age, backoff, retention, batch size, parallelism. See Hooks.

UseS3Archive (from Winche.Storage.S3), UseFileSystemArchive (from Winche.Storage.FileSystem) and MapClaims (from Winche.Storage.AspNetCore) are extension methods on WincheStorageOptions.

S3ArchiveOptions

Property Default Description
BucketName (required) S3 bucket name
RegionName (required) AWS region (e.g. "us-east-1")
AccessKey null Optional — omit to use ambient credentials
SecretKey null Optional — omit to use ambient credentials
ServiceUrl null S3-compatible endpoint (e.g. http://localhost:9000 for MinIO); null targets AWS
ForcePathStyle true Path-style addressing (MinIO and most S3-compatible stores); only used with ServiceUrl
PresignedUrlExpiry 00:15:00 Lifetime of generated presigned URLs

Configure S3 with a delegate (bind from IConfiguration yourself if you prefer):

opts.UseS3Archive(s3 =>
{
    s3.BucketName = "my-bucket";
    s3.RegionName = "eu-west-1";
});

REST Endpoints

Routes are under /files/v1 (the prefix argument of MapWincheStorageRestApi). All {path} segments are base64url-encoded file paths (or directory paths for :list). CRUD uses HTTP methods; per-file operations use AIP-136 colon-verbs (all POST).

Method Route Description
PUT /{path} Register a file, new or replacing the one there (its upload starts over). Body: mimeType, sizeBytes, metadata?, precondition? ({"exists": false} create-only, {"version": n}), contentDisposition?, cacheControl?
GET /{path} Get a file record
PATCH /{path} Merge into the file's metadata ({"metadata": {...}}; a null value removes the key) and set contentDisposition / cacheControl ("" clears); precondition? ({"version": n})
DELETE /{path} Delete the file and every file under path/ (each one rule-checked; one refusal deletes nothing); archive objects are removed best-effort afterward. ?ifVersion=n deletes only that version
GET /ping Liveness check
POST /{path}:confirm Confirm the upload: the stored object must be exactly the declared size; confirming again returns the file
POST /{path}:upload Generate a presigned upload URL
POST /{path}:download Generate a presigned download URL
POST /{path}:list A page of a folder: {items, prefixes, nextPageToken} (?maxResults=&pageToken=&mimeType=); /:list lists the top
POST /{path}:signPart Sign a multipart upload part ({ "partNumber": N })
POST /{path}:listParts List uploaded parts for a multipart upload

MapWincheStorageRestApi returns a single IEndpointConventionBuilder covering every endpoint, so cross-cutting policy applies to all of them:

app.MapWincheStorageRestApi(prefix: "storage")
   .RequireAuthorization();

Request pipeline

Every endpoint runs two built-in filters before the handler decodes the base64url path and calls IFileStorage: the ExceptionHandler outermost (answers failures with the shared Winche error, { "error": { code, message, reason? } }), then the ClaimsAccessor (maps the request to caller claims), so a failing claims mapper gets the same error shape:

flowchart LR
    Req["HTTP<br/>/files/v1/{base64url}:verb"] --> EH["ExceptionHandler"]
    EH --> CA["ClaimsAccessor<br/>SetClaims(HttpContext)"]
    CA --> Handler["handler<br/>DecodePath → IFileStorage"]
    Handler --> Ok["Results.Json"]
    EH -. on exception .-> Err["403 permission-denied<br/>404 not-found<br/>400 invalid-argument (too-large, size-mismatch, invalid-path)<br/>400 failed-precondition (upload-status, not-uploaded, version, not-found)<br/>409 already-exists / aborted<br/>500 internal (details.errorId)"]

Upload lifecycle

A record is registered first (status pending), uploaded directly to the archive via presigned URLs (single or multipart), then confirmed (status complete). Downloads require complete. Confirm checks the stored size against the declared one, and only completes the file it checked: if the file was replaced meanwhile it fails with aborted.

Paths have one accepted form: segments joined by single / (no leading, trailing or doubled /), no . or .. segments, no \ or control characters, at most 1,000 bytes. Anything else is invalid-argument (reason invalid-path), so rules, the database and every archive agree on which file a path means.

Archive keys. Bytes aren't stored at the file's path: each registration uploads to a key of its own, the folder, a random generation, then the name (users/u1/7f3a9c2e41b05d68/photo.jpg). Confirming makes it the file's key and deletes the bytes it replaced. So replacing a file never overwrites bytes in place, an old upload link only reaches a key nothing reads (the orphan sweep removes what it wrote), and a file deleted and created again shares nothing with the old one. Files stored before keep their path as their key.

sequenceDiagram
    actor Client
    participant API as Storage API
    participant Arch as Archive

    Client->>API: PUT /{path}  (register, status=pending)
    alt single upload
        Client->>API: POST /{path}:upload
        API-->>Client: presigned PUT URL
        Client->>Arch: upload object
    else multipart upload
        loop part 1..N
            Client->>API: POST /{path}:signPart {partNumber}
            API-->>Client: presigned part URL
            Client->>Arch: upload part
        end
    end
    Client->>API: POST /{path}:confirm
    API->>Arch: complete / verify object
    API-->>Client: FileRecord (status=complete)
    Client->>API: POST /{path}:download
    API-->>Client: presigned GET URL
stateDiagram-v2
    [*] --> pending: register
    pending --> complete: confirm
    complete --> [*]: download

Preconditions. SetAsync, UpdateMetadataAsync and DeleteAsync take a FilePrecondition(Exists?, Version?), as for a database document: FilePrecondition.IfNotExists (Exists: false) only creates and fails with already-exists; Version: n goes ahead only if the file is still at that version, else failed-precondition (reason version, or not-found when there's no file).

Download headers. FileHeaders(ContentDisposition, CacheControl) (e.g. attachment; filename="a.pdf", public, max-age=3600) are set at registration (SetAsync(headers:)) and changed with UpdateMetadataAsync (null leaves one as is, "" clears it). Downloads are served with the file's recorded mimeType and these headers: S3 signs them into the link as response-header overrides; the folder archive signs them into the link too (t, d, c), so an edited link is refused.

Listing. ListAsync(directory, FileListOptions? options) returns one page of the files directly in the folder (Items) and its sub-folders as full paths (Prefixes), merged in name order. "" is the top folder. MaxResults defaults to and is capped at 1,000; pass NextPageToken back as PageToken for the rest (null on the last page); MimeType filters the files.

Access Control

Authorization is written in the Winche.Rules rules language and loaded with opts.UseRulesFile(...) or opts.UseRulesText(...); there is no C# builder (9.0.0). Access is default-deny: with no matching allow, every protected call throws AccessDeniedException. Multiple calls accumulate and are OR-combined. With the Winche console's rules editor, the version edited there or deployed with winche rules deploy replaces the file's rules at startup.

// storage.rules
match userFiles/{userId}/{rest=**} {
  // Owner has full access to their own subtree, files up to 10 MB.
  allow read, delete: if request.auth.token.userId == userId;
  allow create, update: if request.auth.token.userId == userId
                        && request.resource.size <= 10 * 1024 * 1024;
}

match public/{rest=**} {
  // Anyone may read public files.
  allow read;
}
  • Path patterns use {param} single-segment captures and a {name=**} recursive capture, readable in conditions by name (userId).
  • Operations: read (get + list), write (create + update + delete), or get, list, create, update, delete.
  • The existing file is exposed to conditions as resource — e.g. resource.mimeType, resource.sizeBytes, resource.metadata.ownerId — and the file as it will be as request.resource. Both also take the names contentType and size for mimeType and sizeBytes.
  • Caller claims are exposed under request.auth: request.auth.uid (the uid claim, if any) and request.auth.token.<claim> (any mapped claim).
  • A missing file or a syntax error fails at startup, naming the file, line and column.

Hot-swapping rules at runtime

The guard's engine reads its ruleset from a mutable repository on every evaluation, so rules can be replaced without restarting the app. The write side is registered as a keyed IMutableRuleSetRepository under WincheStorageKeys.RULE_ENGINE_KEY — resolve it and call Update:

using Winche.Rules;
using Winche.Rules.Text;
using Winche.Storage.Constants;

var repo = provider.GetRequiredKeyedService<IMutableRuleSetRepository>(WincheStorageKeys.RULE_ENGINE_KEY);
repo.Update(RuleText.ParseRuleSet("match public/{rest=**} { allow read; }"));

The swap is a lock-free atomic reference write: in-flight evaluations keep the ruleset they started with, and the next call observes the new rules. Update replaces the whole ruleset — build the full set you want live (it is not merged with the rules registered at startup).

Storage operations map to rule operations as follows:

IFileStorage call Rule operation
SetAsync Create when the path is free; Update when it replaces a file (resource the file replaced)
GetAsync, GenerateDownloadUrlAsync, ListUploadedPartsAsync Get
ListAsync List
UpdateMetadataAsync, ConfirmUploadAsync, GenerateUploadUrlAsync, SignPartAsync Update
DeleteAsync Delete, for every file it removes

For SetAsync and UpdateMetadataAsync, request.resource is the file as it would be after the write (for metadata, the merged result), so a rule can protect a key: request.resource.metadata.owner == resource.metadata.owner. GenerateUploadUrlAsync, SignPartAsync and ConfirmUploadAsync have the registered file as both resource and request.resource, so size and type rules written for create or write apply to the upload too. Writes are checked inside their transaction, so the file a rule allowed is the one changed.

ListDirectoryIdsAsync is intentionally absent from this table: it exists only on the concrete FileStorage, never on IFileStorage, and is never rule-evaluated — a privileged, admin-only operation (see Privileged: ListDirectoryIdsAsync below).

Authorization flow

A protected call loads the current record (as resource), gathers caller claims, and asks the RuleEngine. If no rule allows the operation it throws AccessDeniedException (default-deny); otherwise it delegates to the unprotected core. Writes follow the same path, authorizing before the mutation (a create has no prior resource):

sequenceDiagram
    actor Caller
    participant Guard as RuleGuardedFileStorage
    participant Core as FileStorage
    participant Claims as IRuleClaimsAccessor
    participant Engine as RuleEngine

    Caller->>Guard: GetAsync(path)
    Guard->>Core: GetAsync(path)
    Core-->>Guard: FileRecord (resource)
    Guard->>Claims: GetClaims()
    Claims-->>Guard: caller claims
    Guard->>Engine: AllowsAsync(Get, path, request)
    alt allowed
        Engine-->>Guard: true
        Guard-->>Caller: FileRecord
    else denied
        Engine-->>Guard: false
        Guard--xCaller: AccessDeniedException
    end

Claims mapping

MapClaims (from Winche.Storage.AspNetCore) maps the HTTP request to the caller-claims dictionary the rules engine reads. The dictionary is exposed as request.auth.token.*, and a uid key (if present) also as request.auth.uid.

opts.MapClaims(ctx => new Dictionary<string, object?>
{
    ["uid"]    = ctx.User.FindFirst("sub")?.Value,
    ["userId"] = ctx.Request.Headers["X-USER-ID"].ToString(),
});

For non-HTTP callers (background services, tests), inject FileClaimsAccessor and call SetClaims(...) directly before invoking IFileStorage.

Where the bytes live

Winche.Storage keeps each file's record (path, type, size, metadata, upload state) in PostgreSQL and its bytes in an archive — IArchive. Clients never send bytes through the API: they get a short-lived URL from the archive and upload or download straight to and from it. Pick an archive, or write one.

S3 and S3-compatible stores

opts.UseS3Archive(s3 => …) (Winche.Storage.S3): AWS S3, MinIO, Cloudflare R2, Backblaze B2, Wasabi, … Downloads carry the file's type and headers as response-header overrides signed into the link.

A folder on disk (10.0.0)

builder.Services.AddWincheStorage(opts =>
{
    opts.ConnectionString = connectionString;
    opts.UseFileSystemArchive(fs =>
    {
        fs.Root = "/var/lib/myapp/files";                          // a local disk, a mounted volume, a network share
        fs.SigningKey = builder.Configuration["Files:SigningKey"]; // optional: 32+ characters, the same on every instance; derived from the master key (AddWincheConfig) when not set
        fs.PublicBaseUrl = "https://api.example.com";              // optional: the request's own address otherwise
    });
});

app.MapWincheStorageFileSystem();   // serves the URLs, under /_files

Upload and download URLs point at your app and are signed (HMAC-SHA256): each works only for its method and path, an upload only up to the size the file was registered with, and only until it expires (an hour by default). Uploads land in a temporary file and appear whole or not at all; downloads support ranges; multipart uploads work as with S3, each part capped at MaxPartBytes and at the file's declared size. Downloads come from your app's own domain, so nothing uploaded can run there: they're sent with nosniff and a sandbox content-security-policy, and only images (not SVG), audio, video and PDF are shown in place; anything else downloads as an attachment unless the file sets its own contentDisposition. The file's type and headers are signed into the download link (t, d, c), so an edited link is refused. Several instances can share the folder if it's on shared storage. Browser apps on another origin need CORS on the /_files routes, as they would on an S3 bucket.

Your own

Implement IArchive and register it (services.AddSingleton<IArchive, MyArchive>() after AddWincheStorage). What it promises:

Member
GenerateUploadUrlAsync(path, mimeType, size) a URL the client PUTs the whole file to (respond with an ETag)
GenerateDownloadUrlAsync(path, headers) a URL the client GETs it from, served with DownloadHeaders (type, disposition, cache) when given
HeadAsync(path) the stored object's size and ETag, or null if there's none: confirming an upload checks both
DeleteAsync, DeleteObjectsAsync remove objects (a missing one isn't an error)
ListObjectsAsync(prefix) every object and when it changed, for the orphan sweep
IAbandonedUploads.DropAbandonedUploadsAsync (optional) drop unfinished multipart uploads, for archives that keep them
IArchiveContent.OpenReadAsync, WriteAsync (optional) read and write bytes from the server: FileStorage.WriteAsync/OpenReadAsync and moving files between locations
CreateMultipartUploadAsync, SignPartAsync, ListPartsAsync, CompleteMultipartUploadAsync, AbortMultipartUploadAsync multipart uploads: a URL per part, then assembly in part order

Anything that can hand out a URL works — another cloud's signed URLs (Azure SAS, Google Cloud Storage), or endpoints in your own app as Winche.Storage.FileSystem does (its source is a complete example).

Request logging (10.0.0)

opts.LogRequests() logs app requests that go through the access rules in the category Winche.Storage.Requests as structured entries — Operation (storage.create, storage.get, storage.upload, storage.confirm, storage.download, storage.list, …), Path, Principal, Outcome (ok, denied, notFound, invalid) and LatencyMs — with a plain message: "u2 was denied deleting uploads/u1/a.png: no rule allows it." Denied and slow requests always (Warning); successful changes (storage.create, storage.update, storage.delete, storage.upload, storage.confirm) always (Information); successful reads are sampled (SuccessSampleRate, default 0.1). The Winche console's Logs Explorer filters on them.

Hooks

Implement FileStoreHook (behavior only) and register it against a path with UseHooks(h => h.Add<T>(path)). The path is a pattern (literal segments, {id} single-segment captures, and a trailing {name=**} recursive wildcard matching one or more segments; bare */** are not valid). The same hook type can be bound to multiple paths. Hooks are dispatched asynchronously.

Delivery. File changes — registered, upload confirmed, metadata updated, deleted — are written to storage's change feed (winche_files_feed) in the same transaction as the change, and each hook is a durable consumer of that feed with its own cursor, on Winche.Core's feed runner (Winche.Core.Feeds, the same one Winche.Database's hooks use). So:

  • nothing is lost to a restart or a crash — a hook carries on from its cursor when a node is back;
  • a hook runs on one node at a time (a lease; another node takes over if that one goes);
  • a hook gets changes in the order they were committed; one that throws is retried with backoff (1 s, doubling, up to 30 s), holding that hook back; after an hour it becomes a dead letter and the hook moves on — StorageHooks lists them (DeadLettersAsync), retries (RetryAsync) or discards them (DeleteAsync);
  • delivery is at least once: a hook may see a change twice (a node died mid-call), so make side effects idempotent (e.g. skip a report you already emailed).

A hook's identity is its type plus path pattern (its consumer is hooks:<type>|<pattern>): renaming either starts a new hook. A hook keeps changes from when the app starting with it called InitializeWincheStorageAsync. Cursors and dead letters are in Winche.Core's shared tables (winche_feed_cursors, winche_feed_dead_letters, feed storage); the feed keeps changes for HookDeliveryOptions.Retention (7 days) once every hook has them. Tune with opts.HookDelivery = new HookDeliveryOptions { ... }. The two URL events (OnUploadUrlGenerated, OnDownloadUrlGenerated) change no data and stay best-effort, in memory.

public class AuditHook : FileStoreHook
{
    public override Task OnFileRegisteredAsync(FileRecord record, CancellationToken ct) { ... }
    public override Task OnUploadConfirmedAsync(FileRecord record, CancellationToken ct) { ... }
    public override Task OnFileDeletedAsync(string path, CancellationToken ct) { ... }
    public override Task OnMetadataUpdatedAsync(FileRecord record, CancellationToken ct) { ... }
    public override Task OnUploadUrlGeneratedAsync(string path, UploadSession session, CancellationToken ct) { ... }
    public override Task OnDownloadUrlGeneratedAsync(string path, DownloadSession session, CancellationToken ct) { ... }
}

Register: opts.UseHooks(h => h.Add<AuditHook>("userFiles/{userId}/{file=**}")).

Files in database documents

With Winche.Database in the same app, a file reference in a document (fileReferenceValue, e.g. a scan field) can be expanded: expand: ["scan"] returns the file's record (type, size, metadata, upload status; no download link: ask storage for one) under resolved, if the storage rules let the caller get the file, and live subscriptions follow changes to it. Nothing to set up: AddWincheStorage registers the file resolver (Winche.Core's IWincheReferenceResolver).

Before hooks

A FileBeforeHook runs before a file write is saved, inside its transaction, after the access rules allowed it, for callers' writes and the app's own: registering a file (new or a replacement), changing its metadata, deleting it (and each file under a deleted directory). It can refuse the write, or change the metadata and headers saved; never the bytes.

public sealed class Scans : FileBeforeHook
{
    public override Task OnBeforeWriteAsync(FileWrite write, CancellationToken ct)
    {
        if (write.Before?.MetaData["locked"]?.GetValue<bool>() == true) write.Deny("This file is locked.");
        if (write.Operation != FileOperation.Delete)
        {
            write.Metadata!["owner"] = write.Uid ?? "server";
            write.CacheControl = "private, max-age=60";
        }
        return Task.CompletedTask;
    }
}

o.UseHooks(h => h.Before<Scans>("scans/{rest=**}"));

Operation, Before, MimeType, SizeBytes, Metadata (this write's own copy, change it in place), ContentDisposition, CacheControl, Caller / Uid. A refusal answers permissionDenied with your message (reason: "denied"), and a directory delete with one refusal deletes nothing. Keep it quick: side effects belong in a FileStoreHook, which runs after the commit.

Metrics and health

The meter Winche.Storage (WincheStorageMetrics.MeterName, for OpenTelemetry .AddMeter(...)) counts winche.storage.files.registered, .uploads.confirmed, .uploads.bytes, .uploads.refused, .files.deleted, .links.signed (tag kind: upload, part, download) and .access.denied (tag operation). Hook delivery is measured on Winche.Core's Winche.Feed meter (winche.feed.delivered, .lag, .failures, .dead_letters, tagged feed: storage and the hook's consumer).

using Winche.Storage.AspNetCore.HealthChecks;

builder.Services.AddHealthChecks().AddWincheStorageHooks();   // maxLag: 5 minutes by default

The check is degraded when the oldest change a hook hasn't taken is older than maxLag or there are dead letters. StorageHooks.StatusAsync() returns the same: oldest pending, hooks failing, dead letters; ConsumersAsync() per hook.

Orphan Sweep

DeleteAsync treats Postgres as the source of truth: it commits the row removal first, then deletes the archive object best-effort. If the archive call fails, the row is still gone and the object is left as a harmless orphan rather than rolling the delete back (which would leave an undeletable record). Archive deletes never throw out of DeleteAsync.

The background orphan sweep reclaims those leftovers, plus whatever reached a key no file uses (an old upload link), and multipart uploads nobody finished on archives that keep them (IAbandonedUploads: the folder archive; on S3 use a bucket lifecycle rule). Enable it with UseOrphanSweep (requires a real archive such as UseS3Archive or UseFileSystemArchive):

opts.UseOrphanSweep(o =>
{
    o.Interval    = TimeSpan.FromHours(6);    // how often the sweep runs
    o.GraceWindow = TimeSpan.FromHours(24);   // min age before an unreferenced object is purged
    o.Prefix      = null;                     // optional key prefix to scope the sweep
});

A hosted service periodically lists the archive and deletes every object that has no matching winche_files row and is older than GraceWindow. The grace window protects in-flight uploads (object PUT, row not yet committed) from being reaped.

OrphanSweepOptions Default Description
Enabled true Whether it runs (the console can turn it on and off with UseSettings())
Interval 06:00:00 How often the sweep runs
GraceWindow 1.00:00:00 An unreferenced object must be older than this to be purged
Prefix null Optional key prefix; null sweeps the whole bucket

To run a sweep on demand, call the privileged PurgeOrphansAsync on the concrete FileStorage (never on IFileStorage, never rule-evaluated — same privileged model as ListDirectoryIdsAsync). It returns the number of objects identified as orphans and submitted for deletion:

// concrete FileStorage only — privileged, not rule-guarded
Task<int> PurgeOrphansAsync(string? prefix, TimeSpan graceWindow, CancellationToken ct = default);

Custom IArchive implementations must implement ListObjectsAsync (added in 7.0) for the sweep to work; S3Archive already does.

IFileStorage

Inject IFileStorage to interact with the store — it always resolves to the rules guard, which authorizes every call via Winche.Rules. Trusted server-side callers that have no request claims (background services, hooks, schedulers) should inject the concrete FileStorage instead, which is the unguarded core (created by AddWincheStorage; resolve it, don't construct it). This mirrors Winche.Database's IDocumentDatabase (guarded) vs DocumentDatabase (unguarded) split.

// IFileStorage — every call is authorized via Winche.Rules
Task<FileRecord>               SetAsync(string path, string mimeType, long sizeBytes, JsonObject? metadata, FilePrecondition? precondition, FileHeaders? headers, CancellationToken ct);
Task<FileRecord?>              GetAsync(string path, CancellationToken ct);
Task<FileRecord?>              UpdateMetadataAsync(string path, JsonObject patch, FilePrecondition? precondition, FileHeaders? headers, CancellationToken ct);
Task<bool>                     DeleteAsync(string path, FilePrecondition? precondition, CancellationToken ct);
Task<UploadSession>            GenerateUploadUrlAsync(string path, CancellationToken ct);
Task<DownloadSession>          GenerateDownloadUrlAsync(string path, CancellationToken ct);
Task<FileRecord>               ConfirmUploadAsync(string path, CancellationToken ct);
Task<FileListResult>           ListAsync(string directory, FileListOptions? options, CancellationToken ct);
Task<UploadSession>            SignPartAsync(string path, int partNumber, CancellationToken ct);
Task<IEnumerable<FilePart>>    ListUploadedPartsAsync(string path, CancellationToken ct);

For trusted, claim-less callers, inject the concrete core — same surface, no authorization:

public sealed class ReportMailer(FileStorage files)   // concrete FileStorage = unguarded
{
    public Task<DownloadSession> LinkAsync(string path, CancellationToken ct) =>
        files.GenerateDownloadUrlAsync(path, ct);
}

The concrete FileStorage also has server-only members (not rule-checked): WriteAsync(path, Stream content, mimeType, sizeBytes, metadata?, headers?, ct) stores bytes without links (register, write, confirm; hooks fire as for an upload), OpenReadAsync(path, ct) returns the bytes of a complete file or null, and DeleteUnderAsync(prefix, ct) deletes every file under a folder. Bytes need an archive that can read and write them (IArchiveContent: S3, the folder archive, and the location router over them); others throw NotSupportedException.

Privileged: ListDirectoryIdsAsync

Listing the immediate sub-directory names under a directory is a privileged, admin-style operation. It lives only on the concrete FileStorage — never on IFileStorage — and is never evaluated by the rules engine, like Winche.Database's DocumentDatabase.ListCollectionIdsAsync). It is not exposed over the REST API.

// concrete FileStorage only — privileged, not rule-guarded
Task<ListDirectoryIdsResult> ListDirectoryIdsAsync(
    string? parentDirectory, int? pageSize = null, string? pageToken = null, CancellationToken ct = default);

Returns the distinct sub-directory names directly under parentDirectory (or the top-level directories when null/empty), ordered by UTF-8 byte order. Results are keyset-paginated: pass NextPageToken back as pageToken to walk pages (pageSize defaults to 100, capped at 300). Files sitting directly in parentDirectory are not sub-directories and are excluded.

public sealed class Browser(FileStorage files)   // concrete = privileged
{
    public async Task<IReadOnlyList<string>> SubdirsAsync(string dir, CancellationToken ct)
    {
        var all = new List<string>();
        string? token = null;
        do
        {
            var page = await files.ListDirectoryIdsAsync(dir, pageToken: token, ct: ct);
            all.AddRange(page.DirectoryIds);
            token = page.NextPageToken;
        } while (token is not null);
        return all;
    }
}

ListDirectoryIdsResult carries IReadOnlyList<string> DirectoryIds and a string? NextPageToken (null on the last page).

FileRecord

Field Type Description
id string The file's name (last path segment), as a database document's id
path string Full logical path
directory string Parent directory segment
mimeType string MIME type
sizeBytes long Declared file size
uploadStatus UploadStatus pending or complete
contentHash string? Archive object fingerprint (ETag); set on confirm
metadata JsonObject Arbitrary key/value metadata
contentDisposition string? Served on downloads; omitted when null
cacheControl string? Served on downloads; omitted when null
version long Goes up with each registration and metadata change; precondition.version holds a write to it
createdAt DateTime Creation timestamp
updatedAt DateTime Last-modified timestamp

Requirements

  • .NET 10 SDK (net10.0)
  • PostgreSQL for metadata storage
  • An archive for the bytes: an S3-compatible bucket (Winche.Storage.S3) or a folder (Winche.Storage.FileSystem)

License

Elastic License 2.0

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
11.1.0 0 11/18/2026
11.0.0 57 11/17/2026
10.0.0 63 11/16/2026
9.0.0 77 11/12/2026
8.3.0 101 11/11/2026
8.2.0 102 11/9/2026
8.1.0 95 11/9/2026
8.0.0 173 7/5/2026
7.0.0 136 6/30/2026
6.4.0 151 6/25/2026
6.3.0 149 6/21/2026
6.2.0 140 6/20/2026
6.1.0 143 6/20/2026
6.0.0 143 6/17/2026
5.0.0 128 6/17/2026
4.0.0 183 6/16/2026
3.0.0 143 6/15/2026
2.0.1 149 5/27/2026
2.0.0 130 5/27/2026
1.0.0 136 5/25/2026