Neuro.Service.ObjectStorage 1.0.0

Neuro.Service.ObjectStorage

Neuro.Service.ObjectStorage defines the contract surface for provider-agnostic object storage in Neuron. It does not contain a concrete storage provider. Instead, it standardizes how application code creates a scoped storage service, writes and reads objects, lists keys, and discovers optional capabilities such as conditional writes or range reads.

This package is intended to make provider implementations behave consistently at the API boundary. The repository also includes a reusable contract test project that provider-specific packages can run against.

What This Package Covers

• IObjectStorageServiceProvider creates scoped IObjectStorageService instances.
• ObjectContainerSpecifier selects the backing container and optional logical root prefix.
• IObjectStorageService provides object CRUD and listing operations within that scope.
• IObject exposes provider-returned metadata for a stored object.
• Optional interfaces add conditional operations, copy operations, range reads, and container access management.

What This Package Does Not Define

• A concrete storage implementation.
• A MIME-type whitelist or file-extension policy.
• An HTTP controller or router error contract.
• How your host application resolves a provider instance from module parameters or dependency injection.

Basic Usage

IObjectStorageServiceProvider Provider = ResolveProviderSomehow();

ObjectContainerSpecifier Scope = new ObjectContainerSpecifier(
	"public-assets",
	"tenant-a/uploads");

IObjectStorageService Storage = await Provider.CreateStorageServiceAsync(
	Scope,
	CancellationToken.None);

await using MemoryStream Data = new MemoryStream(ImageBytes);

IObject StoredObject = await Storage.PutObjectAsync(
	"images/logo.png",
	Data,
	new ObjectWriteOptions(
		Overwrite: false,
		ContentType: "image/png"),
	CancellationToken.None);

string Key = StoredObject.Key;
string? PublicUrl = StoredObject.PublicUrl;

Behavioral Contract

Scoped keys and root prefixes

• Object keys passed to IObjectStorageService are always relative to the scoped service.
• ObjectContainerSpecifier.RootPrefix is prepended by the provider when addressing the backing store.
• Returned object keys remain relative to the scoped service. Callers should not expect the backing prefix to be echoed back.
• ObjectKey provides normalization helpers for keys, prefixes, and root prefixes.

Write behavior

• PutObjectAsync creates a new object when the key does not already exist.
• ObjectWriteOptions.Overwrite = true allows an existing object to be replaced.
• ObjectWriteOptions.Overwrite = false requires providers to fail duplicate writes with ObjectAlreadyExistsException.
• ContentType, ContentEncoding, and Metadata are storage metadata. This package does not enforce or validate a MIME whitelist.
• A provider or calling application may still reject unsupported values and surface an ObjectStorageException or a more specific provider-mapped exception.

Public URL behavior

• IObject.PublicUrl is optional and nullable by design.
• A non-null value means the provider could determine a publicly reachable URL for the stored object in the current container configuration.
• Callers must not assume PublicUrl is populated for every provider, every container, or every object.
• If public accessibility matters to your application, verify container access behavior separately through provider configuration and optional container-access APIs.

Delete and list behavior

• DeleteObjectAsync is idempotent. Deleting a missing object succeeds without error.
• ListObjectsAsync returns keys relative to the current scope.
• ObjectListOptions.ContinuationToken is opaque and should only be reused with the same listing semantics.

Exception Model

Providers are expected to map common failure modes into the package exception types:

• InvalidObjectKeyException: the supplied object key or prefix violates the contract.
• InvalidObjectStorageScopeException: the requested container scope is invalid.
• ObjectAlreadyExistsException: a write or copy would replace an object when overwrite is not allowed.
• ObjectPreconditionFailedException: conditional request requirements were not satisfied.
• ObjectStorageAccessException: the caller is not permitted to perform the requested operation.
• ObjectStorageException: a general provider failure that does not fit a more specific contract exception.

Optional Capabilities

Providers may implement additional interfaces beyond IObjectStorageService:

• IConditionalObjectOperations for ETag- or version-based conditional writes and deletes.
• IObjectCopyOperations for server-side copies within a scoped container.
• IObjectRangeReadOperations for byte-range downloads.
• IObjectAccessLinkOperations for time-limited links to private objects.
• IContainerAccessManagement for reading or changing container public-access settings.
• IObjectStorageCapabilityProvider for capability discovery without trial-and-error casting.

Optional operations can be obtained without explicit casts:

if (Storage.TryGetAccessLinkOperations(out IObjectAccessLinkOperations? AccessLinks))
{
    ObjectAccessLink Link = await AccessLinks.CreateAccessLinkAsync(
        "private/document.pdf",
        new ObjectAccessLinkOptions(TimeSpan.FromMinutes(15), ObjectAccessPermissions.Read),
        CancellationToken.None);
}

IObjectAccessLinkOperations RequiredAccessLinks = Storage.GetRequiredAccessLinkOperations();

Contract Tests

The repository includes Neuro.Service.ObjectStorage.Test, an MSTest-based contract suite for provider implementations. It verifies the expected semantics for duplicate writes, delete idempotency, root-prefix scoping, paging, conditional operations, and exception mapping.

Use that project when building a concrete provider to keep behavior aligned with the abstractions in this package.