DeepDrftAPI Rename

This commit is contained in:
Daniel Harvey
2026-05-25 10:38:36 -04:00
parent 98b2c8d744
commit 551cef0fe8
59 changed files with 510 additions and 524 deletions
+221
View File
@@ -0,0 +1,221 @@
# CLAUDE.md - DeepDrftContent
Guidance for working in the DeepDrftContent project (the binary content API host).
See the root `CLAUDE.md` for full architecture overview. This file covers what is specific to this project.
## One-line purpose
The dual-database authority for tracks: SQL metadata and FileDatabase binary. Seven endpoints expose track CRUD with upload+persist, delete+cleanup, paged listing, and metadata operations. ApiKey middleware, CORS, forwarded headers. **FileDatabase implementation lives in `DeepDrftContent.Services`; SQL services in `DeepDrftData`.**
## What lives here now (only)
- `Program.cs`, `Startup.cs`: HTTP host config, DI wiring, middleware setup, port binding.
- `Services/UnifiedTrackService.cs`: Host-internal orchestrator. Coordinates vault write + SQL persist for upload (`UploadAsync`), and SQL delete + vault remove for delete (`DeleteAsync`).
- `Controllers/TrackController.cs`: Seven endpoints (see below).
- `Middleware/ApiKeyAuthenticationMiddleware.cs`, `Middleware/ApiKeyAuthorizeAttribute.cs`: ApiKey validation logic.
- `Models/`: Settings POCOs only (`ApiKeySettings`, `CorsSettings`, `FileDatabaseSettings`). No domain code.
- `environment/filedatabase.json`: FileDatabase vault path config (loaded via CredentialTools, not in repo).
- `environment/apikey.json`: API key (loaded via CredentialTools, not in repo, must be created locally or at deployment).
- `environment/connections.json`: SQL connection string (loaded via CredentialTools, not in repo, format: `{ "ConnectionStrings": { "DefaultConnection": "..." } }`).
## What does NOT live here anymore
- `FileDatabase/`, `Processors/`, media models (`AudioBinary`, `ImageBinary`, etc.), `WavOffsetService` — all in `DeepDrftContent.Services`.
- EF Core context and repository — in `DeepDrftData`.
- **Hosts only own HTTP surface and wiring.** New domain code goes in `*.Services` (shared libraries) or host-internal `Services/` folders (e.g., `UnifiedTrackService` here for dual-database orchestration).
## The endpoint surface (seven endpoints)
### GET api/track/{trackId}?offset=0 (unauthenticated)
Returns the WAV bytes from the `tracks` vault with optional offset support.
- **Route parameter `trackId`** (string): the entry id inside the `tracks` vault (i.e. `TrackEntity.EntryKey`).
- **Query parameter `offset`** (optional, default 0): byte position to start streaming from.
- If `offset == 0`: streams the entire file directly from disk without buffering (so 100 MB WAVs do not force 100 MB LOH allocations per request).
- If `offset > 0`: `WavOffsetService.CreateOffsetStream` block-aligns the offset and synthesises a fresh 44-byte WAV header so the response is a valid standalone WAV starting from that byte position. This is load-bearing for seek-beyond-buffer — the player asks for a new stream at the offset it wants to seek to, gets back a valid WAV that starts there, and tears down/re-initialises the decoder.
- Returns 404 if track not found. Returns 500 if vault operations fail (with error swallowing — the vault returns `null`).
### PUT api/track/{trackId} ([ApiKeyAuthorize])
**Authenticated endpoint.** Writes pre-processed audio bytes to the `tracks` vault.
- **Header `ApiKey`**: required. Validated by `ApiKeyAuthenticationMiddleware`.
- **Route parameter `trackId`** (string): the entry id to store under.
- **Body**: `AudioBinaryDto` (base64 buffer + size + mime + duration + bitrate). This endpoint receives an already-processed audio DTO, not a raw WAV file.
- Validates MIME type (rejects unsupported types with `.bin` sentinel). Delegates to `FileDatabase.RegisterResourceAsync`.
- Rarely used in production (the CLI calls `FileDatabase.RegisterResourceAsync` directly). Exists for potential future web-side intake paths.
- Returns 200 on success, 401 if ApiKey invalid, 400 if MIME invalid.
### POST api/track/upload ([ApiKeyAuthorize])
**Authenticated endpoint.** Accepts a raw WAV upload + metadata as `multipart/form-data`, processes the WAV, stores it in the vault, and persists metadata to SQL. Returns the fully persisted `TrackEntity` with `Id` populated.
- **Header `ApiKey`**: required. Validated by `ApiKeyAuthenticationMiddleware`.
- **Form fields**:
- `wav` (`IFormFile`, required): the WAV bytes. File name must end in `.wav`.
- `trackName` (string, required)
- `artist` (string, required)
- `album` (string, optional)
- `genre` (string, optional)
- `releaseDate` (string, optional, format `YYYY-MM-DD`)
- `createdByUserId` (long, required): audit trail — who uploaded this track.
- The upload stream is copied to a `.wav`-suffixed temp file under `Path.GetTempPath()` (the audio processor requires that extension and reads from disk). The temp file is always deleted in a `finally` block — success or failure.
- `[RequestSizeLimit(1 GB)]` + `[RequestFormLimits(MultipartBodyLengthLimit = 1 GB)]` lift the per-request ceiling above the framework default (~28 MB) so production-sized WAVs are accepted. The body is streamed to the temp file, not buffered in memory.
- Calls `UnifiedTrackService.UploadAsync`, which orchestrates: `TrackService.AddTrackFromWavAsync` (vault write) → `TrackManager` (SQL persist with `createdByUserId`).
- Returns 200 with the **persisted** `TrackEntity` JSON (Id populated) on success. Returns 400 for missing/invalid form fields. Returns 500 if processing fails.
### DELETE api/track/{id:long} ([ApiKeyAuthorize])
**Authenticated endpoint.** Removes a track: SQL row first, then vault entry. `UnifiedTrackService` owns the ordering.
- **Header `ApiKey`**: required. Validated by `ApiKeyAuthenticationMiddleware`.
- **Route parameter `id`** (long): the SQL track ID (not EntryKey).
- Calls `UnifiedTrackService.DeleteAsync`, which: looks up SQL row → deletes SQL row → deletes vault entry via EntryKey.
- Returns 200 on success, 404 if track not found, 500 if deletion fails.
### GET api/track/page ([ApiKeyAuthorize])
**Authenticated endpoint.** Paged metadata list from SQL. Used by CMS track browser.
- **Header `ApiKey`**: required. Validated by `ApiKeyAuthenticationMiddleware`.
- **Query parameters**:
- `page` (int, optional, default 1): 1-based page number.
- `pageSize` (int, optional, default 20): tracks per page.
- `sortColumn` (string, optional): sort field. Supported: `"TrackName"`, `"Artist"`, `"Album"`, `"Genre"`, `"ReleaseDate"`. Defaults to `Id`.
- `sortDescending` (bool, optional, default false): sort direction.
- Calls `ITrackService.GetPaged` (via DI), which is actually `TrackManager` from `DeepDrftData`.
- Returns 200 with `PagedResult<TrackEntity>` JSON (`Items`, `TotalCount`, `PageNumber`, `PageSize`). Returns 500 on query error.
### GET api/track/meta/{id:long} ([ApiKeyAuthorize])
**Authenticated endpoint.** Single track metadata from SQL by ID.
- **Header `ApiKey`**: required. Validated by `ApiKeyAuthenticationMiddleware`.
- **Route parameter `id`** (long): the SQL track ID.
- Calls `ITrackService.GetById`, which returns the track or null.
- Returns 200 with `TrackEntity` JSON on success. Returns 404 if not found. Returns 500 on query error.
### PUT api/track/meta/{id:long} ([ApiKeyAuthorize])
**Authenticated endpoint.** Updates track metadata in SQL. EntryKey (the vault link) is immutable.
- **Header `ApiKey`**: required. Validated by `ApiKeyAuthenticationMiddleware`.
- **Route parameter `id`** (long): the SQL track ID.
- **Body**: `UpdateTrackMetadataRequest` with fields: `TrackName`, `Artist`, `Album?`, `Genre?`, `ReleaseDate?`.
- Looks up SQL row by ID, updates the provided fields (nulls in the request clear optional fields), and persists via `ITrackService.Update`.
- Returns 200 on success. Returns 404 if track not found. Returns 500 on update error.
## ApiKey middleware behaviour
`ApiKeyAuthenticationMiddleware` runs on every request but only enforces on endpoints with `[ApiKeyAuthorize]` metadata.
- Reads header `ApiKey`.
- Compares against `ApiKeySettings.ApiKey` from `environment/apikey.json`.
- Returns 401 with body `"API Key was not provided"` or `"Unauthorized client"` if validation fails.
- Endpoints without `[ApiKeyAuthorize]` skip the check entirely (e.g., `GET api/track/{id}` is unauthenticated).
## CORS configuration
`CorsSettings.AllowedOrigins` is **required** — the app throws on startup if missing. Policy is named `ContentApiPolicy`:
- `AllowCredentials()`
- `AllowAnyMethod()`
- `AllowAnyHeader()`
Configured in `Startup.ConfigureDomainServices()`, applied to all endpoints via `UseCors()`.
## Forwarded headers
**Enabled only in `Production` mode** (via `if (app.Environment.IsProduction())`). This differs from `DeepDrftWeb`, which enables them always. Be aware when debugging proxy issues.
`UseForwardedHeaders()` processes `X-Forwarded-For`, `X-Forwarded-Proto`, `X-Forwarded-Host` so the app knows its real client IP and scheme when sitting behind nginx.
## Startup wiring (Startup.ConfigureDomainServices + Program.cs)
**In `Startup.ConfigureDomainServices`** (FileDatabase + binary services):
1. Load `environment/filedatabase.json` via `CredentialTools.ResolvePathOrThrow("filedatabase", ...)` and bind `FileDatabaseSettings`.
2. Await `FileDatabase.FromAsync(VaultPath)` to load or create the database.
3. Register `FileDatabase` as singleton.
4. Ensure the `tracks` vault exists (type `MediaVaultType.Audio`, created on first boot if missing).
5. Register singletons: `WavOffsetService`, `AudioProcessor`, `TrackService` (the `DeepDrftContent.Data` version for vault operations).
**In `Program.cs`** (SQL + wiring):
6. Load `environment/connections.json` via `CredentialTools.ResolvePathOrThrow("connections", ...)`.
7. Register `DbContext<DeepDrftContext>` (scoped) with connection string from config.
8. Register scoped: `TrackRepository`, `TrackManager`, `ITrackService` (factory resolves to `TrackManager`), `UnifiedTrackService`.
9. Configure forwarded headers (production-only) for reverse proxy support.
10. Load `environment/apikey.json` and register API key middleware.
11. Configure CORS policy (`ContentApiPolicy`): AllowAnyMethod, AllowAnyHeader, AllowCredentials, specific origins from config.
The singleton `FileDatabase` is thread-safe for reads. Writes are atomic at the vault level (index updates are serialised). The `IndexWatcher` reloads the vault index if an external process (e.g., CLI) writes to it, so a long-running web host stays consistent. SQL services are scoped (DbContext not thread-safe).
## OpenAPI
Mapped in `Development` only. Swagger UI at `/swagger` for testing endpoints locally.
## Configuration files
- `appsettings.json`: Logging, hosting, and CORS config. **Does not contain secrets.**
- `Logging`: standard ASP.NET structure.
- `CorsSettings.AllowedOrigins`: array of origin URLs allowed to call the API (required; throws on startup if missing).
- `environment/filedatabase.json` (required, loaded via CredentialTools, not in repo):
```json
{
"FileDatabaseSettings": {
"VaultPath": "../Database/Vaults"
}
}
```
- `environment/apikey.json` (required at runtime, loaded via CredentialTools, not in repo):
```json
{
"ApiKeySettings": {
"ApiKey": "your-secret-key"
}
}
```
- `environment/connections.json` (required, loaded via CredentialTools, not in repo):
```json
{
"ConnectionStrings": {
"DefaultConnection": "Host=localhost;Database=deepdrft;Username=postgres;Password=..."
}
}
```
## Development commands
```bash
# Run the content API (default https://localhost:5002)
dotnet run --project DeepDrftContent
# Watch during development
dotnet watch run --project DeepDrftContent
# Build
dotnet build DeepDrftContent
# Test endpoints (requires API key in environment/apikey.json)
curl -H "ApiKey: your-secret-key" -X PUT https://localhost:5002/api/track/test-id \
-H "Content-Type: application/json" \
-d '{"buffer":"base64-encoded-audio","size":1000,"mime":"audio/wav"}'
curl https://localhost:5002/api/track/test-id?offset=0
```
## Important patterns
- **Result types**: Controllers return `ActionResult<T>`. Service calls return `Result` or `ResultContainer<T>` from NetBlocks. The controller checks `Success` and returns 200/4xx/5xx accordingly.
- **Error swallowing**: FileDatabase operations return `null` or `false` on failure. The controller surfaces this as 500. Never throw — check return values.
- **Async/await**: All operations are async.
- **Vault operations**: Always use the injected `FileDatabase` singleton. Never construct a new one — it has the `IndexWatcher` and is the source of truth.
## The FileDatabase import
See `DeepDrftContent.Services/CLAUDE.md` for the FileDatabase API and semantics. This host only provides the HTTP surface over it.
When working with this project, focus on the HTTP surface (controllers, middleware, CORS, forwarded headers) and the wiring that connects the host to the FileDatabase. New domain logic goes in `DeepDrftContent.Services`.
+374
View File
@@ -0,0 +1,374 @@
using DeepDrftAPI.Middleware;
using DeepDrftAPI.Models;
using DeepDrftAPI.Services;
using DeepDrftContent.Audio;
using DeepDrftContent.Constants;
using DeepDrftContent.FileDatabase.Services;
using DeepDrftContent.FileDatabase.Models;
using DeepDrftData;
using Microsoft.AspNetCore.Mvc;
namespace DeepDrftAPI.Controllers;
[ApiController]
[Route("api/[controller]")]
public class TrackController : ControllerBase
{
private readonly DeepDrftContent.TrackContentService _trackContentService;
private readonly WavOffsetService _wavOffsetService;
private readonly UnifiedTrackService _unifiedService;
private readonly ITrackService _sqlTrackService;
private readonly ILogger<TrackController> _logger;
// FileDatabase is injected directly for PutTrack because that endpoint receives a pre-processed
// AudioBinaryDto over the wire, not a WAV file path. TrackContentService.AddTrackFromWavAsync is
// file-path-oriented and not applicable here. If a file-upload flow is added in future,
// route it through TrackContentService instead.
private readonly DeepDrftContent.FileDatabase.Services.FileDatabase _fileDatabase;
public TrackController(
DeepDrftContent.TrackContentService trackContentService,
DeepDrftContent.FileDatabase.Services.FileDatabase fileDatabase,
WavOffsetService wavOffsetService,
UnifiedTrackService unifiedService,
ITrackService sqlTrackService,
ILogger<TrackController> logger)
{
_trackContentService = trackContentService;
_fileDatabase = fileDatabase;
_wavOffsetService = wavOffsetService;
_unifiedService = unifiedService;
_sqlTrackService = sqlTrackService;
_logger = logger;
}
// --- Literal-segment routes first ---
// These are declared before the parameterized "{trackId}" / "{id:long}" actions so route
// resolution never treats "page", "upload", or "meta" as a trackId.
// GET api/track/page?page=1&pageSize=20&sortColumn=TrackName&sortDescending=false
// CMS metadata listing — paged read straight from SQL.
[ApiKeyAuthorize]
[HttpGet("page")]
public async Task<ActionResult> GetPage(
[FromQuery] int page = 1,
[FromQuery] int pageSize = 20,
[FromQuery] string? sortColumn = null,
[FromQuery] bool sortDescending = false,
CancellationToken cancellationToken = default)
{
var result = await _sqlTrackService.GetPaged(page, pageSize, sortColumn, sortDescending, cancellationToken);
if (!result.Success || result.Value is null)
{
var error = result.Messages.FirstOrDefault()?.Message ?? "Unknown error";
_logger.LogError("GetPage failed: {Error}", error);
return StatusCode(500, "Failed to load tracks");
}
return Ok(result.Value);
}
// POST api/track/upload: raw WAV in (multipart/form-data) + metadata → persisted TrackEntity out.
// Used by the CMS upload flow on DeepDrftManager; that host proxies the upload here so it never
// touches the vault disk path or SQL directly. UnifiedTrackService owns the two-database write.
//
// RequestSizeLimit/MultipartBodyLengthLimit set to 1 GB: WAV uploads can be tens to hundreds
// of MB and the framework defaults (~28 MB) reject them outright. The IFormFile path streams
// the body to a temp file once Kestrel surfaces it, so the limit is the per-request ceiling,
// not a buffered allocation.
[ApiKeyAuthorize]
[HttpPost("upload")]
[RequestSizeLimit(1_073_741_824)]
[RequestFormLimits(MultipartBodyLengthLimit = 1_073_741_824)]
public async Task<ActionResult<DeepDrftModels.Entities.TrackEntity>> UploadTrack(
[FromForm] IFormFile? wav,
[FromForm] string? trackName,
[FromForm] string? artist,
[FromForm] string? album,
[FromForm] string? genre,
[FromForm] string? releaseDate,
[FromForm] long createdByUserId,
CancellationToken cancellationToken)
{
_logger.LogInformation("UploadTrack called: trackName={TrackName}, artist={Artist}, size={Size}",
trackName, artist, wav?.Length);
if (wav is null || wav.Length == 0)
{
return BadRequest("WAV file is required");
}
if (string.IsNullOrWhiteSpace(trackName))
{
return BadRequest("trackName is required");
}
if (string.IsNullOrWhiteSpace(artist))
{
return BadRequest("artist is required");
}
if (!string.Equals(Path.GetExtension(wav.FileName), ".wav", StringComparison.OrdinalIgnoreCase))
{
return BadRequest("Uploaded file must have a .wav extension");
}
DateOnly? parsedReleaseDate = null;
if (!string.IsNullOrWhiteSpace(releaseDate))
{
if (!DateOnly.TryParseExact(releaseDate, "yyyy-MM-dd", out var parsed))
{
return BadRequest("releaseDate must be in YYYY-MM-DD format");
}
parsedReleaseDate = parsed;
}
// AudioProcessor.ProcessWavFileAsync requires a path ending in .wav and reads from disk.
// Path.GetTempFileName() yields .tmp, which fails that check — generate our own .wav path.
var tempPath = Path.Combine(Path.GetTempPath(), Guid.NewGuid().ToString("N") + ".wav");
try
{
await using (var tempStream = new FileStream(
tempPath, FileMode.CreateNew, FileAccess.Write, FileShare.None,
bufferSize: 81920, useAsync: true))
await using (var uploadStream = wav.OpenReadStream())
{
await uploadStream.CopyToAsync(tempStream, cancellationToken);
}
var result = await _unifiedService.UploadAsync(
tempPath,
trackName,
artist,
string.IsNullOrWhiteSpace(album) ? null : album,
string.IsNullOrWhiteSpace(genre) ? null : genre,
parsedReleaseDate,
createdByUserId,
cancellationToken);
if (!result.Success || result.Value is null)
{
var error = result.Messages.FirstOrDefault()?.Message ?? "Failed to process and store WAV";
_logger.LogWarning("UploadTrack: UnifiedTrackService failed for {TrackName}: {Error}", trackName, error);
return StatusCode(500, error);
}
_logger.LogInformation("UploadTrack succeeded: id={Id}, entryKey={EntryKey}", result.Value.Id, result.Value.EntryKey);
return Ok(result.Value);
}
catch (Exception ex)
{
_logger.LogError(ex, "UploadTrack failed for {TrackName}", trackName);
return StatusCode(500, "Internal server error");
}
finally
{
try
{
if (System.IO.File.Exists(tempPath))
{
System.IO.File.Delete(tempPath);
}
}
catch (Exception ex)
{
_logger.LogWarning(ex, "UploadTrack: failed to delete temp file {TempPath}", tempPath);
}
}
}
// GET api/track/meta/{id}: single track metadata from SQL.
[ApiKeyAuthorize]
[HttpGet("meta/{id:long}")]
public async Task<ActionResult> GetMeta(long id)
{
var result = await _sqlTrackService.GetById(id);
if (!result.Success)
{
var error = result.Messages.FirstOrDefault()?.Message ?? "Unknown error";
_logger.LogError("GetMeta failed for {TrackId}: {Error}", id, error);
return StatusCode(500, "Failed to load track");
}
if (result.Value is null)
{
return NotFound();
}
return Ok(result.Value);
}
// PUT api/track/meta/{id}: metadata-only update. EntryKey is immutable and not part of the body.
[ApiKeyAuthorize]
[HttpPut("meta/{id:long}")]
public async Task<ActionResult> UpdateMeta(long id, [FromBody] UpdateTrackMetadataRequest request)
{
var lookup = await _sqlTrackService.GetById(id);
if (!lookup.Success)
{
var error = lookup.Messages.FirstOrDefault()?.Message ?? "Unknown error";
_logger.LogError("UpdateMeta lookup failed for {TrackId}: {Error}", id, error);
return StatusCode(500, "Failed to load track");
}
if (lookup.Value is null)
{
return NotFound();
}
var track = lookup.Value;
track.TrackName = request.TrackName;
track.Artist = request.Artist;
track.Album = request.Album;
track.Genre = request.Genre;
track.ReleaseDate = request.ReleaseDate;
var update = await _sqlTrackService.Update(track);
if (!update.Success)
{
var error = update.Messages.FirstOrDefault()?.Message ?? "Unknown error";
_logger.LogError("UpdateMeta failed for {TrackId}: {Error}", id, error);
return StatusCode(500, "Failed to update track");
}
return Ok();
}
// DELETE api/track/{id}: removes the SQL row then the vault entry. UnifiedTrackService owns
// the ordering and orphan handling. Declared (with the long route constraint) before the
// string "{trackId}" GET so a numeric id routes here.
[ApiKeyAuthorize]
[HttpDelete("{id:long}")]
public async Task<ActionResult> DeleteTrack(long id, CancellationToken cancellationToken)
{
_logger.LogInformation("DeleteTrack called with id: {Id}", id);
var result = await _unifiedService.DeleteAsync(id, cancellationToken);
if (result.Success)
{
return Ok();
}
var error = result.Messages.FirstOrDefault()?.Message ?? "Unknown error";
if (string.Equals(error, UnifiedTrackService.TrackNotFoundMessage, StringComparison.Ordinal))
{
return NotFound();
}
_logger.LogError("DeleteTrack failed for id {Id}: {Error}", id, error);
return StatusCode(500, error);
}
// --- Parameterized routes ---
[HttpGet("{trackId}")]
public async Task<ActionResult> GetTrack(string trackId, [FromQuery] long offset = 0)
{
_logger.LogInformation("GetTrack called with trackId: {TrackId}, offset: {Offset}", trackId, offset);
try
{
// No-offset path: stream the file straight from disk so a 100 MB WAV does not
// force a 100 MB LOH allocation per request. The offset path still loads
// the full buffer because WavOffsetService block-aligns and reslices into
// a composite stream over the in-memory buffer.
if (offset == 0)
{
var vault = _fileDatabase.GetVault(VaultConstants.Tracks);
if (vault == null)
{
_logger.LogWarning("Tracks vault not found");
return NotFound();
}
var mediaStream = await vault.GetEntryStreamAsync(trackId);
if (mediaStream == null)
{
_logger.LogWarning("Track not found: {TrackId}", trackId);
return NotFound();
}
// Resolve MIME and log before handing the stream to File().
// If anything here throws, the finally block disposes the wrapper
// (and its inner FileStream) so neither leaks. On the success path
// File() takes ownership of the inner stream; ASP.NET Core disposes
// it after the response body is sent. The wrapper is a thin struct
// with no extra resources, so disposing it after extracting the
// inner stream is a no-op — we only call Dispose() in the catch path.
string streamMimeType;
long streamLength;
Stream innerStream;
try
{
streamMimeType = MimeTypeExtensions.GetMimeType(mediaStream.Extension);
streamLength = mediaStream.Stream.Length;
innerStream = mediaStream.Stream;
}
catch
{
await mediaStream.DisposeAsync();
throw;
}
_logger.LogInformation(
"Streaming track from disk: {TrackId}, Size: {Size} bytes",
trackId, streamLength);
// enableRangeProcessing: false — seek is served by WavOffsetService, not Range.
return File(innerStream, streamMimeType, enableRangeProcessing: false);
}
// Offset path: route through TrackContentService.GetAudioBinaryAsync (Track B's
// orchestrator boundary) so the controller stays out of FileDatabase directly.
// The buffered AudioBinary is required because WavOffsetService block-aligns
// and reslices into a composite stream over the in-memory buffer.
var file = await _trackContentService.GetAudioBinaryAsync(trackId);
if (file == null)
{
_logger.LogWarning("Track not found: {TrackId}", trackId);
return NotFound();
}
var mimeType = MimeTypeExtensions.GetMimeType(file.Extension);
var offsetStream = _wavOffsetService.CreateOffsetStream(file.Buffer, offset);
if (offsetStream == null)
{
_logger.LogWarning("Invalid offset {Offset} for track: {TrackId}", offset, trackId);
return BadRequest("Invalid offset");
}
_logger.LogInformation("Successfully retrieved track with offset: {TrackId}, Offset: {Offset}, StreamSize: {Size} bytes",
trackId, offset, offsetStream.Length);
return File(offsetStream, mimeType);
}
catch (Exception ex)
{
_logger.LogError(ex, "Error retrieving track: {TrackId}", trackId);
return StatusCode(500, "Internal server error");
}
}
[ApiKeyAuthorize]
[HttpPut("{trackId}")]
public async Task<ActionResult> PutTrack(string trackId, [FromBody] AudioBinaryDto track)
{
_logger.LogInformation("PutTrack called with trackId: {TrackId}", trackId);
// Reject unknown MIME types up front rather than silently storing the binary
// with a ".bin" extension. GetExtension returns ".bin" for any unrecognised
// MIME, so treat that as the sentinel for an unsupported type.
if (MimeTypeExtensions.GetExtension(track.Mime) == ".bin")
{
_logger.LogWarning("PutTrack rejected: unsupported MIME type '{Mime}' for track {TrackId}", track.Mime, trackId);
return BadRequest($"Unsupported MIME type: {track.Mime}");
}
var audioBinary = AudioBinary.From(track);
// Direct FileDatabase write: this endpoint receives an already-processed AudioBinaryDto,
// not a WAV file, so TrackContentService.AddTrackFromWavAsync does not apply. See constructor comment.
var success = await _fileDatabase.RegisterResourceAsync(
DeepDrftContent.Constants.VaultConstants.Tracks, trackId, audioBinary);
return success ? Ok() : BadRequest("Failed to store audio track");
}
}
+27
View File
@@ -0,0 +1,27 @@
<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>net10.0</TargetFramework>
<Nullable>enable</Nullable>
<ImplicitUsings>enable</ImplicitUsings>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.1" />
<!-- EF Core / Npgsql kept in sync with DeepDrftData / DeepDrftManager so the same DbContext registration compiles. -->
<PackageReference Include="Microsoft.EntityFrameworkCore" Version="10.0.7" />
<PackageReference Include="Microsoft.EntityFrameworkCore.Relational" Version="10.0.7" />
<PackageReference Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="10.0.1" />
</ItemGroup>
<ItemGroup>
<ProjectReference Include="..\DeepDrftModels\DeepDrftModels.csproj" />
<ProjectReference Include="..\DeepDrftContent\DeepDrftContent.csproj" />
<ProjectReference Include="..\DeepDrftData\DeepDrftData.csproj" />
</ItemGroup>
<ItemGroup>
<Folder Include="Middleware\" />
</ItemGroup>
</Project>
+6
View File
@@ -0,0 +1,6 @@
@DeepDrftContent_HostAddress = http://localhost:5070
GET {{DeepDrftContent_HostAddress}}/weatherforecast/
Accept: application/json
###
@@ -0,0 +1,57 @@
using System.Reflection;
namespace DeepDrftAPI.Middleware
{
public class ApiKeyAuthenticationMiddleware
{
private readonly RequestDelegate _next;
private readonly string _apiKey;
public ApiKeyAuthenticationMiddleware(RequestDelegate next, string apiKey)
{
_next = next;
_apiKey = apiKey ?? throw new ArgumentNullException(nameof(apiKey));
}
public async Task InvokeAsync(HttpContext context)
{
var endpoint = context.GetEndpoint();
if (endpoint == null)
{
await _next(context);
return;
}
var hasApiKeyAuthorize = endpoint.Metadata.GetMetadata<ApiKeyAuthorizeAttribute>() != null;
if (!hasApiKeyAuthorize)
{
await _next(context);
return;
}
if (!context.Request.Headers.TryGetValue("ApiKey", out var extractedApiKey))
{
context.Response.StatusCode = 401;
await context.Response.WriteAsync("API Key was not provided");
return;
}
if (!string.Equals(extractedApiKey, _apiKey, StringComparison.Ordinal))
{
context.Response.StatusCode = 401;
await context.Response.WriteAsync("Unauthorized client");
return;
}
await _next(context);
}
}
public static class ApiKeyAuthenticationMiddlewareExtensions
{
public static IApplicationBuilder UseApiKeyAuthentication(this IApplicationBuilder builder, string apiKey)
{
return builder.UseMiddleware<ApiKeyAuthenticationMiddleware>(apiKey);
}
}
}
@@ -0,0 +1,7 @@
namespace DeepDrftAPI.Middleware
{
[AttributeUsage(AttributeTargets.Class | AttributeTargets.Method, AllowMultiple = false, Inherited = true)]
public class ApiKeyAuthorizeAttribute : Attribute
{
}
}
+7
View File
@@ -0,0 +1,7 @@
namespace DeepDrftAPI.Models
{
public class ApiKeySettings
{
public required string ApiKey { get; set; }
}
}
+6
View File
@@ -0,0 +1,6 @@
namespace DeepDrftAPI.Models;
public class CorsSettings
{
public string[] AllowedOrigins { get; set; } = [];
}
@@ -0,0 +1,7 @@
namespace DeepDrftAPI.Models
{
public class FileDatabaseSettings
{
public required string VaultPath { get; set; }
}
}
@@ -0,0 +1,12 @@
namespace DeepDrftAPI.Models;
/// <summary>
/// Body of <c>PUT api/track/meta/{id}</c>. Metadata-only — EntryKey is immutable and never
/// travels over this surface.
/// </summary>
public record UpdateTrackMetadataRequest(
string TrackName,
string Artist,
string? Album,
string? Genre,
DateOnly? ReleaseDate);
+86
View File
@@ -0,0 +1,86 @@
using DeepDrftAPI;
using DeepDrftAPI.Middleware;
using DeepDrftAPI.Models;
using DeepDrftAPI.Services;
using DeepDrftData;
using DeepDrftData.Data;
using DeepDrftData.Repositories;
using Microsoft.AspNetCore.HttpOverrides;
using Microsoft.EntityFrameworkCore;
using NetBlocks.Utilities.Environment;
var builder = WebApplication.CreateBuilder(args);
// Add services to the container.
await Startup.ConfigureDomainServices(builder);
builder.Services.AddControllers();
// Learn more about configuring OpenAPI at https://aka.ms/aspnet/openapi
builder.Services.AddOpenApi();
// Add CORS policy using configured origins
var corsSettings = builder.Configuration.GetSection(nameof(CorsSettings)).Get<CorsSettings>();
if (corsSettings?.AllowedOrigins == null || corsSettings.AllowedOrigins.Length == 0)
{
throw new Exception("CorsSettings.AllowedOrigins configuration is required for CORS policy");
}
builder.Services.AddCors(options =>
{
options.AddPolicy("ContentApiPolicy", policy =>
{
policy.WithOrigins(corsSettings.AllowedOrigins)
.AllowAnyMethod()
.AllowAnyHeader()
.AllowCredentials();
});
});
// Load API key via CredentialTools (dev: environment/apikey.json; prod: CREDENTIALS_DIRECTORY/apikey)
var apiKeyPath = CredentialTools.ResolvePathOrThrow("apikey", "environment/apikey.json");
builder.Configuration.AddJsonFile(apiKeyPath, optional: false, reloadOnChange: false);
var apiKeySettings = builder.Configuration.GetSection(nameof(ApiKeySettings)).Get<ApiKeySettings>();
if (apiKeySettings is null) { throw new Exception("API key settings are not configured"); }
// SQL connection string — DeepDrftAPI now owns both vault (FileDatabase) and SQL metadata.
var connectionsPath = CredentialTools.ResolvePathOrThrow("connections", "environment/connections.json");
builder.Configuration.AddJsonFile(connectionsPath, optional: false, reloadOnChange: false);
// SQL metadata domain — DbContext + repository + manager (scoped; DbContext is not thread-safe).
// UnifiedTrackService orchestrates the two databases and is the single authority over track data.
builder.Services.AddDbContext<DeepDrftContext>(options =>
options.UseNpgsql(builder.Configuration.GetConnectionString("DefaultConnection")));
builder.Services
.AddScoped<TrackRepository>()
.AddScoped<TrackManager>()
.AddScoped<ITrackService>(sp => sp.GetRequiredService<TrackManager>());
builder.Services.AddScoped<UnifiedTrackService>();
// Configure forwarded headers for reverse proxy support
builder.Services.Configure<ForwardedHeadersOptions>(options =>
{
options.ForwardedHeaders = ForwardedHeaders.XForwardedFor | ForwardedHeaders.XForwardedProto | ForwardedHeaders.XForwardedHost;
// Trust any proxy (nginx) - in production, specify known proxy networks
options.KnownNetworks.Clear();
options.KnownProxies.Clear();
});
var app = builder.Build();
if (app.Environment.IsProduction())
{
// Use forwarded headers before other middleware
app.UseForwardedHeaders();
}
if (app.Environment.IsDevelopment())
{
app.MapOpenApi();
}
app.UseCors("ContentApiPolicy");
app.UseApiKeyAuthentication(apiKeySettings.ApiKey);
app.MapControllers();
app.Run();
+118
View File
@@ -0,0 +1,118 @@
using DeepDrftContent;
using DeepDrftContent.Constants;
using DeepDrftData;
using DeepDrftModels.Entities;
using NetBlocks.Models;
using FileDb = DeepDrftContent.FileDatabase.Services.FileDatabase;
namespace DeepDrftAPI.Services;
/// <summary>
/// Host-internal orchestrator that makes DeepDrftAPI the single authority over both the
/// vault (FileDatabase) and SQL metadata (DeepDrftData). Owns the two-database write/delete
/// flow so the controller stays a thin HTTP boundary and no caller coordinates the two stores.
/// </summary>
public class UnifiedTrackService
{
internal const string TrackNotFoundMessage = "Track not found.";
private readonly TrackContentService _contentTrackContentService;
private readonly ITrackService _sqlTrackService;
private readonly FileDb _fileDatabase;
private readonly ILogger<UnifiedTrackService> _logger;
public UnifiedTrackService(
TrackContentService contentTrackContentService,
ITrackService sqlTrackService,
FileDb fileDatabase,
ILogger<UnifiedTrackService> logger)
{
_contentTrackContentService = contentTrackContentService;
_sqlTrackService = sqlTrackService;
_fileDatabase = fileDatabase;
_logger = logger;
}
/// <summary>
/// Process a WAV into the vault, then persist its metadata to SQL. On success the returned
/// entity carries the SQL-assigned Id. If the vault write succeeds but the SQL persist fails,
/// the audio is orphaned under EntryKey — logged loudly so it is recoverable manually.
/// </summary>
public async Task<ResultContainer<TrackEntity>> UploadAsync(
string tempFilePath,
string trackName,
string artist,
string? album,
string? genre,
DateOnly? releaseDate,
long createdByUserId,
CancellationToken ct)
{
var unpersisted = await _contentTrackContentService.AddTrackFromWavAsync(
tempFilePath, trackName, artist, album, genre, releaseDate);
if (unpersisted is null)
{
_logger.LogWarning("UploadAsync: content TrackContentService returned null for {TrackName}", trackName);
return ResultContainer<TrackEntity>.CreateFailResult("Failed to process and store WAV.");
}
unpersisted.CreatedByUserId = createdByUserId;
var saveResult = await _sqlTrackService.Create(unpersisted);
if (!saveResult.Success || saveResult.Value is null)
{
// Vault write succeeded, SQL persist failed — audio is orphaned in the tracks vault
// under EntryKey. Log loudly (include EntryKey) so it is recoverable manually.
var error = saveResult.Messages.FirstOrDefault()?.Message ?? "Unknown error";
_logger.LogError(
"Track persisted to vault but SQL save failed. Orphaned entry: {EntryKey}. Error: {Error}",
unpersisted.EntryKey, error);
return ResultContainer<TrackEntity>.CreateFailResult($"Track was uploaded but could not be saved: {error}");
}
return saveResult;
}
/// <summary>
/// Delete a track's SQL row, then its vault entry. SQL is the source of truth: a SQL delete
/// failure fails the operation (and leaves the vault untouched), but a subsequent vault delete
/// failure is logged as an orphan and swallowed — it is a maintenance concern, not user-facing.
/// </summary>
public async Task<Result> DeleteAsync(long id, CancellationToken ct)
{
var lookup = await _sqlTrackService.GetById(id);
if (!lookup.Success)
{
var error = lookup.Messages.FirstOrDefault()?.Message ?? "unknown error";
_logger.LogError("DeleteAsync: GetById failed for track {TrackId}: {Error}", id, error);
return Result.CreateFailResult("Failed to load track.");
}
if (lookup.Value is null)
{
return Result.CreateFailResult(TrackNotFoundMessage);
}
var entryKey = lookup.Value.EntryKey;
var sqlDelete = await _sqlTrackService.Delete(id);
if (!sqlDelete.Success)
{
var error = sqlDelete.Messages.FirstOrDefault()?.Message ?? "unknown error";
_logger.LogError("DeleteAsync: SQL delete failed for track {TrackId}: {Error}", id, error);
return Result.CreateFailResult("Failed to delete track.");
}
// Tri-state per FileDatabase's error-swallow contract: null = vault missing/error,
// false = entry not present, true = removed. Anything but a clean removal is an orphan.
var removed = await _fileDatabase.RemoveResourceAsync(VaultConstants.Tracks, entryKey);
if (removed is not true)
{
_logger.LogWarning(
"Vault delete did not remove entry after SQL delete. {TrackId} {EntryKey} outcome={Outcome}",
id, entryKey, removed);
}
return Result.CreatePassResult();
}
}
+49
View File
@@ -0,0 +1,49 @@
using DeepDrftAPI.Models;
using DeepDrftContent;
using DeepDrftContent.Audio;
using DeepDrftContent.Constants;
using DeepDrftContent.FileDatabase.Models;
using DeepDrftContent.FileDatabase.Services;
using DeepDrftContent.Processors;
using Microsoft.Extensions.Logging;
using NetBlocks.Utilities.Environment;
namespace DeepDrftAPI
{
public static class Startup
{
public static Task ConfigureDomainServices(WebApplicationBuilder builder)
{
// Audio services
builder.Services.AddSingleton<WavOffsetService>();
builder.Services.AddSingleton<AudioProcessor>();
builder.Services.AddSingleton<TrackContentService>();
// File Database
var fileDatabasePath = CredentialTools.ResolvePathOrThrow("filedatabase", "environment/filedatabase.json");
builder.Configuration.AddJsonFile(fileDatabasePath, optional: false, reloadOnChange: false);
var fileDatabaseSettings = builder.Configuration.GetSection(nameof(FileDatabaseSettings)).Get<FileDatabaseSettings>();
if (fileDatabaseSettings is null) { throw new Exception("File database settings are not configured"); }
var vaultPath = fileDatabaseSettings.VaultPath;
builder.Services.AddSingleton(sp =>
{
var logger = sp.GetRequiredService<ILogger<FileDatabase>>();
var db = FileDatabase.FromAsync(vaultPath, logger).GetAwaiter().GetResult();
if (db is null) throw new Exception("Unable to initialize file database");
InitializeTrackVault(db).GetAwaiter().GetResult();
return db;
});
return Task.CompletedTask;
}
private static async Task InitializeTrackVault(FileDatabase fileDatabase)
{
if (!fileDatabase.HasVault(VaultConstants.Tracks))
{
await fileDatabase.CreateVaultAsync(VaultConstants.Tracks, MediaVaultType.Audio);
}
}
}
}
+5
View File
@@ -0,0 +1,5 @@
{
"ApiKeySettings": {
"ApiKey": "your-secret-api-key-here"
}
}
+20
View File
@@ -0,0 +1,20 @@
{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft.AspNetCore": "Warning",
"DeepDrftContent.Controllers.TrackController": "Information"
}
},
"AllowedHosts": "*",
"CorsSettings": {
"AllowedOrigins": [
"https://localhost:12778",
"https://deepdrft.com",
"https://www.deepdrft.com"
]
},
"ForwardedHeaders": {
"DisableHttpsRedirection": "true"
}
}
+5
View File
@@ -0,0 +1,5 @@
{
"FileDatabaseSettings": {
"VaultPath": "<path-to-vault>"
}
}