timothy
214fad2dcd
`api.paging-zero-based` says `pageNum` is 0-based across `/api/v1` and every wrapper of it. That was true of the MCP tool catalog and the docs, and not true of the generated OpenAPI document: all 24 paging parameters across the 12 paged operations were emitted with no `description` at all, so a consumer reading only `v1.json` — the intended contract, and what generated clients surface to their users — had to infer the base from `default: 0`. That is the same inference that cost #487 a verification pass on the MCP side, where the description was present but wrong. Annotates each `[FromQuery]` paging parameter with `[Description]` (`System.ComponentModel`), the mechanism `parentId` already used in ImagesController, and regenerates `v1.json`. `pageSize` states the endpoint's OWN cap, because the caps genuinely differ — 100 typical, 200 auto-tune members, 1000 search/all-items — and the record forbids documenting one global number; it also states that the offset derives from the effective (capped) size, so an over-large `pageSize` narrows the page instead of widening the offset. The generated TypeScript client covers DTOs only, not query parameters, so it is unchanged; `endpoint-index.md` carries summaries, not parameter descriptions, so it is unchanged too. Pinned by OpenApiPagingContractTests against the in-process generated document. The test NAMES the expected set of 12 paged operations rather than only filtering for parameters called `pageNum`: a filter cannot see an endpoint that should page and doesn't, which is exactly how two MCP tools escaped the equivalent check in #616. Set equality is asserted in both directions, and the caps are pinned per endpoint so a description naming the wrong cap fails — a wrong justification outlives a wrong line. Mutation-verified both ways: dropping one `[Description]` reddens the description test, and making one endpoint stop exposing `pageNum`/`pageSize` under those names reddens the set-equality test. Refs #633 Decisions-Edit: yes
74 lines
3.1 KiB
C#
74 lines
3.1 KiB
C#
using System.ComponentModel;
|
|
using System.Linq.Expressions;
|
|
using ErsatzTV.Application.Logs;
|
|
using ErsatzTV.Core.Api.Logs;
|
|
using ErsatzTV.Filters;
|
|
using MediatR;
|
|
using Microsoft.AspNetCore.Http;
|
|
using Microsoft.AspNetCore.Mvc;
|
|
|
|
namespace ErsatzTV.Controllers.Api;
|
|
|
|
[ApiController]
|
|
[RequiresAuthentication]
|
|
public class LogsController(IMediator mediator) : ControllerBase
|
|
{
|
|
private const int MaxPageSize = 100;
|
|
|
|
// Mirrors the sortable columns from the legacy Blazor Logs.razor (MudTableSortLabel on
|
|
// Timestamp/Level; Message was never sortable there either).
|
|
private static readonly System.Collections.Generic.HashSet<string> AllowedSortFields =
|
|
new(StringComparer.OrdinalIgnoreCase) { "timestamp", "level" };
|
|
|
|
[HttpGet("/api/v1/logs", Name = "GetLogs")]
|
|
[Tags("Logs")]
|
|
[EndpointSummary("Get recent log entries")]
|
|
[EndpointDescription(
|
|
"sortField is validated against an allow-list (timestamp, level); an unrecognized value " +
|
|
"falls back to timestamp. sortDirection accepts asc/desc and falls back to desc (the " +
|
|
"pre-existing default, newest first).")]
|
|
[EndpointGroupName("general")]
|
|
[ProducesResponseType(typeof(PagedLogEntriesResponseModel), StatusCodes.Status200OK)]
|
|
public async Task<PagedLogEntriesResponseModel> GetLogs(
|
|
[FromQuery]
|
|
[Description("0-based page index: the first page is 0, not 1. A negative value is clamped to 0.")]
|
|
int pageNum = 0,
|
|
[FromQuery]
|
|
[Description("Rows per page (default 100); capped at 100 for this endpoint. The page offset is derived from the effective (capped) size, so a larger value narrows the page instead of widening the offset.")]
|
|
int pageSize = 100,
|
|
[FromQuery] string filter = "",
|
|
[FromQuery] string sortField = "timestamp",
|
|
[FromQuery] string sortDirection = "desc",
|
|
CancellationToken cancellationToken = default)
|
|
{
|
|
int clampedPageNum = Math.Max(0, pageNum);
|
|
int clampedPageSize = Math.Clamp(pageSize, 1, MaxPageSize);
|
|
|
|
string normalizedSortField = AllowedSortFields.Contains(sortField ?? string.Empty)
|
|
? sortField!.ToLowerInvariant()
|
|
: "timestamp";
|
|
bool descending = !string.Equals(sortDirection, "asc", StringComparison.OrdinalIgnoreCase);
|
|
|
|
Expression<Func<LogEntryViewModel, object>> sortExpression = normalizedSortField switch
|
|
{
|
|
"level" => le => le.Level,
|
|
_ => le => le.Timestamp
|
|
};
|
|
|
|
PagedLogEntriesViewModel result = await mediator.Send(
|
|
new GetRecentLogEntries(clampedPageNum, clampedPageSize, filter ?? string.Empty)
|
|
{
|
|
SortExpression = sortExpression,
|
|
SortDescending = descending
|
|
},
|
|
cancellationToken);
|
|
|
|
return new PagedLogEntriesResponseModel(
|
|
result.TotalCount,
|
|
result.Page.Map(ProjectToResponseModel).ToList());
|
|
}
|
|
|
|
private static LogEntryResponseModel ProjectToResponseModel(LogEntryViewModel viewModel) =>
|
|
new(viewModel.Timestamp, viewModel.Level.ToString(), viewModel.Message);
|
|
}
|