114 lines
9.8 KiB
Markdown
114 lines
9.8 KiB
Markdown
# Glossary
|
||
|
||
Core terminology. Read before working on unfamiliar areas.
|
||
|
||
## Core Abstractions
|
||
|
||
| Term | Definition |
|
||
|---|---|
|
||
| **IId<T>** | Generic identity interface (`T` = `Guid` or `int`). Foundation of the entity system. |
|
||
| **TrackingState** | Client-side change tracking enum: Added, Modified, Deleted, Unchanged. Not related to EF Core tracking. |
|
||
| **IForeignKey** | Marker interface for navigation property foreign keys. |
|
||
| **IForeignCollection<T>** | Marker for collection navigation properties. |
|
||
|
||
## Serialization Formats
|
||
|
||
| Term | Definition |
|
||
|---|---|
|
||
| **AcBinary** | High-perf binary serializer. Two-phase: scan (metadata) → serialize. Reference tracking, string interning, ID-based dedup. |
|
||
| **Toon** | Token-Oriented Object Notation. LLM-optimized: @meta (schema) + @data (values), maximized for LLM comprehension. |
|
||
| **AcJson** | Newtonsoft.Json wrapper: $id/$ref handling, IId-based resolution, chain deserialization API. |
|
||
| **Chain API** | Fluent deserialization: `CreateDeserializeChain<T>().ThenDeserialize<U>()...Execute()`. Resolves cross-refs across multiple types. |
|
||
| **String Interning** | Binary serializer dedup of repeated strings. Controlled via `[AcStringIntern]` or `StringInterningMode`. See `AyCode.Core/AyCode.Core/docs/BINARY/BINARY_FEATURES.md`. |
|
||
|
||
## Binary Wire Format
|
||
|
||
For full specification see `AyCode.Core/AyCode.Core/docs/BINARY/BINARY_FORMAT.md`.
|
||
|
||
| Term | Definition |
|
||
|---|---|
|
||
| **BinaryTypeCode** | Single-byte marker that identifies the type of the next value in the binary stream. 100+ codes defined in `BinaryTypeCode.cs`. |
|
||
| **FixObj** | Compact object marker (0–63). The byte itself is the type slot index — no additional identifier needed. |
|
||
| **FixStr** | Compact string marker (103–134). Encodes type + length in one byte for ASCII strings ≤31 bytes. |
|
||
| **TinyInt** | Compact integer marker (192–255). Encodes small integers (−16 to 47) in a single byte. |
|
||
| **VarInt / VarUInt** | Variable-length integer encoding. LEB128 for unsigned, ZigZag + LEB128 for signed. |
|
||
| **SequenceBinaryInput** | `struct : IBinaryInputBase` for reading multi-segment pipe data (`ReadOnlySequence<byte>`). Lazy iteration, zero-alloc ctor, `ArrayPool` scratch for cross-segment reads. Full spec: `AyCode.Core/AyCode.Core/docs/BINARY/BINARY_FORMAT.md`. |
|
||
| **ArrayBinaryInput** | `struct : IBinaryInputBase` for reading from contiguous `byte[]`. Zero-copy when pipe is single-segment. Default fast-path for deserialization. |
|
||
| **HeaderFlags** | Byte at stream position 1 encoding serialization options: metadata, reference handling mode, cache count presence. Base `0x90`. |
|
||
| **Two-Phase Serialization** | Scan pass detects multi-referenced objects, serialize pass writes output using reference table. Required for `ReferenceHandling.All`. |
|
||
|
||
## Serialization Attributes
|
||
|
||
| Attribute | Purpose |
|
||
|---|---|
|
||
| **[AcBinarySerializable]** | Marks type for source generator. Feature flags: enableMetadata, enableIdTracking, enableRefHandling, enableInternString. |
|
||
| **[AcStringIntern]** | Marks string property for deduplication during binary serialization. |
|
||
| **[ToonDescription]** | Per-property description for Toon @meta output. |
|
||
|
||
## Architecture Layers
|
||
|
||
| Layer | Projects | Role |
|
||
|---|---|---|
|
||
| **Interfaces** | AyCode.Interfaces, .Server | Contracts only — no implementation |
|
||
| **Entities** | AyCode.Entities, .Server | Abstract generic base classes |
|
||
| **Models** | AyCode.Models, .Server | DTOs, view models |
|
||
| **Services** | AyCode.Services, .Server | Business logic, SignalR |
|
||
| **Database** | AyCode.Database | EF Core DAL with Session/Transaction pattern |
|
||
| **Core** | AyCode.Core, .Server | Serializers, compression, logging, constants |
|
||
| **Utils** | AyCode.Utils, .Server | Zero-dependency utilities |
|
||
|
||
## Database Patterns
|
||
|
||
| Term | Definition |
|
||
|---|---|
|
||
| **DAL (Data Access Layer)** | `AcDalBase` — mutex-protected, supports Session (read) and Transaction (write) patterns. |
|
||
| **PooledDal** | Singleton pool managing DAL instances by SessionId/PlayerId. |
|
||
| **Session** | Read-only database operation pattern. No transaction, no mutex lock on DbContext. |
|
||
| **Transaction** | Write operation pattern with auto-rollback on failure. |
|
||
|
||
## SignalR Infrastructure
|
||
|
||
For full architecture see `AyCode.Services/docs/SIGNALR/README.md`.
|
||
|
||
| Term | Definition |
|
||
|---|---|
|
||
| **OnReceiveMessage** | Single SignalR method for all communication. Tag-based routing via `int messageTag`; metadata + payload as separate hub args. Full spec: `AyCode.Services/docs/SIGNALR/README.md`. |
|
||
| **SignalParams** | Metadata accompanying each message (separate hub arg). Carries Status, response type, packed parameters, raw-bytes flag. `[AcBinarySerializable]`. Full spec: `AyCode.Services/docs/SIGNALR/README.md`. |
|
||
| **Message Tag** | Integer identifier mapping to a method via `[SignalR(tag)]` or `[SignalRSendToClient(tag)]` attributes. |
|
||
| **DynamicMethodRegistry** | Resolves message tags to `MethodInfo` at runtime. Static `ConcurrentDictionary` cache with lazy scan on miss. |
|
||
| **SignalRCrudTags** | Sealed class bundling 5 independent tag integers (getAllTag, getItemTag, addTag, updateTag, removeTag) for entity CRUD. See `AyCode.Services.Server/docs/SIGNALR_DATASOURCE/README.md`. |
|
||
| **AcBinaryHubProtocol** | Unsealed base `IHubProtocol` replacing SignalR's JSON+Base64 with `AcBinarySerializer`. Protocol name: `"acbinary"`. Full spec (write/read paths, chunked framing): `AyCode.Services/docs/SIGNALR_BINARY_PROTOCOL/README.md`. |
|
||
| **AyCodeBinaryHubProtocol** | Consumer-derived protocol (per-message header with type resolution, `IsRawBytesData`). Registered via `AddAcBinaryProtocol(...)` DI extension on both server and client. Full spec: `AyCode.Services/docs/SIGNALR/README.md`. |
|
||
| **AcBinaryHubProtocolOptions** | Mutable config for protocol registration (SerializerOptions, ProtocolMode, BufferSize, FlushTimeout, etc.). `Validate()` + `Clone()` for DI safety. Full spec: `AyCode.Services/docs/SIGNALR/README.md`. |
|
||
| **AcSignalRProtocolExtensions** | DI extension class: `AddAcBinaryProtocol(ISignalRServerBuilder, Action<AcBinaryHubProtocolOptions>?)` for server, `AddAcBinaryProtocol(IHubConnectionBuilder, Action<...>?)` for client. DI `IOptions<T>` + inline-configure override chain. |
|
||
| **SignalResponseDataMessage** | Internal DTO for client callback routing and stream wire format (not serialized as envelope on wire). `RawResponseData` is `object?` (typed object or byte[]). `GetResponseData<T>()` performs direct cast. |
|
||
| **SignalPostJsonDataMessage** | OBSOLETE — still exists but marked `[Obsolete]`. Legacy: serialized params to JSON inside Binary envelope. |
|
||
| **AcSignalRDataSource** | Generic real-time `IList<T>` with change tracking, CRUD via SignalRCrudTags, binary merge, rollback, sync state. |
|
||
| **TrackingItem** | Wraps a modified DataSource item with `TrackingState` (Add/Update/Remove) + `OriginalValue` for rollback. |
|
||
| **SendToClientType** | Enum controlling broadcast scope: None, Others, Caller, All. |
|
||
| **AcWebSignalRHubBase** | Abstract server hub. Receives `OnReceiveMessage` (with `object data`), dispatches via DynamicMethodRegistry, responds via `SendMessageToClient` (builds response `SignalParams` with `SignalDataType` + passes `object responseData` — protocol zero-copy serializes to pipe). |
|
||
| **AcSignalRClientBase** | Abstract client. Manages `HubConnection`, request/response correlation via `requestId`, pooled `SignalRRequestModel`. `SendCoreAsync` builds `SignalParams` (with `IsRawBytesData` when `T == byte[]`). |
|
||
| **AcSessionService** | `ConcurrentDictionary`-based session tracker for connected SignalR clients. |
|
||
| **AcSignalRSendToClientService** | Server-push service: `SendMessageToAllClients`, `SendMessageToConnection`, `SendMessageToUser`. |
|
||
| **Working Reference List** | DataSource feature: `SetWorkingReferenceList()` allows external list to become inner storage (zero-copy). |
|
||
|
||
## Logging
|
||
|
||
For full architecture see `AyCode.Core/AyCode.Core/docs/LOGGING/README.md`.
|
||
|
||
| Term | Definition |
|
||
|---|---|
|
||
| **LogLevel** | Byte enum: Detail(0), Trace(5), Debug(10), Info(15), Suggest(17), Warning(20), Error(25), Disabled(255). Values are DB-synced — do NOT renumber. |
|
||
| **AcLoggerBase** | Abstract logger with multi-writer fan-out. Two-level filtering: logger-level + per-writer level. Implements both `IAcLogWriterBase` and MS `ILogger`. |
|
||
| **AcLogWriterBase** | Abstract writer base. Own `LogLevel` loaded from appsettings by `AssemblyQualifiedName` match. Two branches: text (`AcTextLogWriterBase`) and structured (`AcLogItemWriterBase<T>`). |
|
||
| **AcTextLogWriterBase** | Text formatting base. Format: `[HH:mm:ss.fff] [AppType[0]] [Level] [Category->Method] [ThreadId] Text`. |
|
||
| **AcConsoleLogWriter** | Colored console writer. Gray=≤Trace, Cyan=Suggest, Yellow=Warning, Red=≥Error. Thread-safe via static lock. |
|
||
| **AcLogItemWriterBase\<T\>** | Abstract structured writer. ThreadPool dispatch + Mutex serialization. `Activator.CreateInstance<T>()` factory for log items. |
|
||
| **GlobalLogger** | Server-side singleton wrapping `AcGlobalLoggerBase`. Static methods for all log levels. Default category: `"GLOBAL_LOGGER"`. |
|
||
| **AcLoggerProvider\<T\>** | `ILoggerProvider` implementation with `ConcurrentDictionary<string, T>` per-category cache. Registered via `AddAcLogger<T>()` or `UseOnlyAcLogger<T>()`. |
|
||
| **IAcLogItemClient** | Structured log item DTO interface. Fields: TimeStampUtc, AppType, LogLevel, ThreadId, CategoryName, CallerName, Text, Exception, ErrorType. |
|
||
| **AcLogItemClient** | `[MessagePackObject]` implementation of `IAcLogItemClient`. Client-side transport entity. |
|
||
| **AcLogItem** | Server-side entity extending `AcLogItemClient`. `[Table("LogItem")]` with auto-generated `Id` and `LogHeaderId`. |
|
||
| **AcLoggerSignalRHub\<T\>** | Server hub receiving log items via `AddLogItem(AcLogItem)`. Simple `Hub` (not tag-based dispatch). |
|
||
| **IAcLogWriterClientBase** | Empty marker interface for client-side writers (`: IAcLogWriterBase`). |
|