Loretta
affa85e5c5
Refactor docs: topic folders, TOON, XCUT, protocol sync - Migrated all topic documentation into dedicated folders with canonical `README.md`, `ISSUES.md`, and `TODO.md` per topic (e.g., `LOGGING/`, `SIGNALR/`, `BINARY/`, `TOON/`). - Added comprehensive TOON serializer documentation: design, format, options, attributes, inference, issues, and TODOs. - Introduced `XCUT` folder for cross-cutting issues and TODOs, with canonical entries and topic cross-references. - Updated all references and navigation to use new folder-based doc paths; fixed links and clarified doc structure. - Enhanced AI agent protocol: enforce session skill preloading, `[LOADED_DOCS: ...]` short-name prefix, and mandatory `docs-check` skill for doc/code sync. - Updated `.csproj` to include all `README.md` files for IDE visibility. - Improved and clarified SignalR, grid, and project-level documentation. - Minor code/test tweaks and doc content corrections for consistency. |
||
|---|---|---|
| .. | ||
| README.md | ||
README.md
Remote Log Writers
Client-side log writers that send log data to remote endpoints. Source: Loggers/ in this project. For core logging framework see AyCode.Core/AyCode.Core/docs/LOGGING/README.md. For server-side GlobalLogger see AyCode.Core.Server/docs/LOGGING/README.md.
AcBrowserConsoleLogWriter
Blazor browser console writer. Extends AcTextLogWriterBase (text branch, not structured). Uses IJSRuntime to invoke browser console methods:
| LogLevel | JS method |
|---|---|
| Detail – Suggest | console.info |
| Warning | console.warn |
| Error | console.error |
Implements IAcLogWriterClientBase (client-side marker).
AcHttpClientLogItemWriter<TLogItem>
HTTP POST writer. Extends AcLogItemWriterBase<TLogItem> (structured branch). Manages its own HttpClient + HttpClientHandler. Sends log items as JSON:
_httpClient.PostAsJsonAsync(_url, logItem).Forget();
Note: Forget() — fire-and-forget, no await on the HTTP response. HTTP/2 by default.
AcSignaRClientLogItemWriter
SignalR log transport writer. Extends AcLogItemWriterBase<AcLogItemClient>. Sends items to a dedicated logger hub. Manages its own HubConnection:
_hubConnection.SendAsync("AddLogItem", logItem).Forget();
UTC conversion note: SignalR doesn't transmit DateTime.Kind. The writer calls logItem.TimeStampUtc.ToUniversalTime() before sending to ensure the server receives actual UTC.
Connection lifecycle: StartConnection() waits up to 10s for Connected state. StopConnection() stops and disposes the hub.
Remote Logging Flow
Client applications can send log items to a server via SignalR:
Client App Server
────────── ──────
AcSignaRClientLogItemWriter AcLoggerSignalRHub<TLogger>
│ │
│ logItem.ToUniversalTime() │
│ StartConnection() │
├──SendAsync("AddLogItem", item)──► │
│ ├─ logItem.TimeStampUtc = UtcNow
│ ├─ _logger.Write(logItem)
│ │ ├─ Console writer
│ │ ├─ DB writer
│ │ └─ ... (all server writers)
Note: AcLoggerSignalRHub overrides the client's TimeStampUtc with DateTime.UtcNow on the server side for authoritative timestamps. The hub is a simple Hub (not AcWebSignalRHubBase) — it does NOT use tag-based dispatch.
Key Source Files
| Component | Path |
|---|---|
| Browser writer | Loggers/AcBrowserConsoleLogWriter.cs |
| HTTP writer | Loggers/AcHttpClientLogItemWriter.cs |
| SignalR writer | Loggers/AcSignaRClientLogItemWriter.cs |
| Structured writer base | AyCode.Entities/AcLogItemWriterBase.cs |
| DB writer | AyCode.Database/AcDbLogItemWriter.cs |
| Logger hub (server) | AyCode.Services.Server/SignalRs/AcLoggerSignalRHub.cs |