Winche.Storage
11.0.0
See the version list below for details.
dotnet add package Winche.Storage --version 11.0.0
NuGet\Install-Package Winche.Storage -Version 11.0.0
<PackageReference Include="Winche.Storage" Version="11.0.0" />
<PackageVersion Include="Winche.Storage" Version="11.0.0" />
<PackageReference Include="Winche.Storage" />
paket add Winche.Storage --version 11.0.0
#r "nuget: Winche.Storage, 11.0.0"
#:package Winche.Storage@11.0.0
#addin nuget:?package=Winche.Storage&version=11.0.0
#tool nuget:?package=Winche.Storage&version=11.0.0
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), orget,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 asrequest.resource. Both also take the namescontentTypeandsizeformimeTypeandsizeBytes. - Caller claims are exposed under
request.auth:request.auth.uid(theuidclaim, if any) andrequest.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 —
StorageHookslists 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
IArchiveimplementations must implementListObjectsAsync(added in 7.0) for the sweep to work;S3Archivealready 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 | Versions 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. |
-
net10.0
- Microsoft.Extensions.Hosting.Abstractions (>= 10.0.5)
- Microsoft.Extensions.Options.ConfigurationExtensions (>= 10.0.5)
- Npgsql (>= 10.0.2)
- Npgsql.DependencyInjection (>= 10.0.2)
- Winche.Core (>= 2.0.0)
- Winche.Rules (>= 5.0.0)
- Winche.Secrets (>= 2.0.0)
NuGet packages (7)
Showing the top 5 NuGet packages that depend on Winche.Storage:
| Package | Downloads |
|---|---|
|
Winche.Storage.AspNetCore.Rest
ASP.NET Core minimal-API endpoints for Winche.Storage, with pluggable claims mapping and exception handling. |
|
|
Winche.Storage.S3
AWS S3 archive backend for Winche.Storage, supporting presigned URLs, multipart uploads, and IAM or key-based authentication. |
|
|
Winche.Storage.AspNetCore
ASP.NET Core integration base for Winche.Storage: HTTP-context claims mapping for the Winche.Rules guard. |
|
|
Winche.Console
An embeddable admin console for Winche.Database and Winche.Storage. Drop it into your ASP.NET Core app to browse and edit JSON documents and manage stored files through a web UI, with its own authentication and role-based access. |
|
|
Winche.Storage.FileSystem
A local-disk (or mounted volume) archive backend for Winche.Storage: files in a folder, uploaded and downloaded through HMAC-signed, expiring URLs served by your own app, with multipart uploads. |
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 | 90 | 11/17/2026 |
| 10.0.0 | 78 | 11/16/2026 |
| 9.0.0 | 89 | 11/12/2026 |
| 8.3.0 | 118 | 11/11/2026 |
| 8.2.0 | 126 | 11/9/2026 |
| 8.1.0 | 115 | 11/9/2026 |
| 8.0.0 | 283 | 7/5/2026 |
| 7.0.0 | 165 | 6/30/2026 |
| 6.4.0 | 173 | 6/25/2026 |
| 6.3.0 | 266 | 6/21/2026 |
| 6.2.0 | 169 | 6/20/2026 |
| 6.1.0 | 170 | 6/20/2026 |
| 6.0.0 | 179 | 6/17/2026 |
| 5.0.0 | 166 | 6/17/2026 |
| 4.0.0 | 210 | 6/16/2026 |
| 3.0.0 | 165 | 6/15/2026 |
| 2.0.1 | 155 | 5/27/2026 |
| 2.0.0 | 146 | 5/27/2026 |
| 1.0.0 | 141 | 5/25/2026 |