91 lines
5.9 KiB
Markdown
91 lines
5.9 KiB
Markdown
# Glossary
|
||
|
||
Core terminology for the AyCode framework. Read this 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-performance binary serializer. Two-phase: scan (collect metadata) then serialize. Supports reference tracking, string interning, ID-based deduplication. |
|
||
| **Toon** | Token-Oriented Object Notation. LLM-optimized format with @meta (schema) and @data (values) sections. Designed for maximum LLM comprehension accuracy. |
|
||
| **AcJson** | Newtonsoft.Json wrapper with $id/$ref reference handling, IId-based resolution, and chain deserialization API. |
|
||
| **Chain API** | Fluent deserialization: `CreateDeserializeChain<T>().ThenDeserialize<U>()...Execute()`. Resolves cross-references across multiple types. |
|
||
| **String Interning** | Binary serializer deduplicates repeated strings. Controlled via `[AcStringIntern]` attribute or `StringInterningMode`. See [BINARY_FORMAT.md](BINARY_FORMAT.md#string-interning-protocol). |
|
||
|
||
## Binary Wire Format
|
||
|
||
For full specification see [`BINARY_FORMAT.md`](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. |
|
||
| **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 Dispatch
|
||
|
||
For full architecture see [`SIGNALR_ARCHITECTURE.md`](SIGNALR_ARCHITECTURE.md).
|
||
|
||
| Term | Definition |
|
||
|---|---|
|
||
| **OnReceiveMessage** | The single SignalR method used for all communication in both directions. Signature: `(int messageTag, byte[] messageBytes, int? requestId)`. |
|
||
| **Message Tag** | Integer identifier that maps to a specific method via `[SignalR(tag)]` or `[SignalRSendToClient(tag)]` attributes. |
|
||
| **TagAttribute** | Base attribute associating an integer tag with a method. `SignalRAttribute` and `SignalRSendToClientAttribute` extend it. |
|
||
| **DynamicMethodRegistry** | Reflection-based registry that resolves message tags to `MethodInfo` at runtime. Uses `ConcurrentDictionary` + `FrozenDictionary` caching. |
|
||
| **AcDynamicMethodCallModel** | Per-instance-type method cache. Builds a `FrozenDictionary<int, AcMethodInfoModel>` once per type via reflection. |
|
||
| **SignalRCrudTags** | Sealed record mapping 5 sequential tags (GetAll, GetItem, Add, Update, Remove) for entity CRUD. `GetMessageTagByTrackingState()` maps `TrackingState` → tag. |
|
||
| **AcBinaryHubProtocol** | Custom `IHubProtocol` replacing SignalR's JSON+Base64 with `AcBinarySerializer`. Protocol name: `"acbinary"`. |
|
||
| **SignalPostJsonDataMessage\<T\>** | ⚠️ TEMPORARY — Message that serializes request parameters to JSON inside a Binary envelope. Planned for replacement with pure Binary. |
|
||
| **SignalResponseDataMessage** | Response message supporting Binary or JSON+GZip serialization. Responses already use pure Binary (no JSON overhead). |
|
||
| **AcSignalRDataSource** | Server-side `IList<T>` with `ChangeTracking` and SignalR CRUD via `SignalRCrudTags`. Supports binary merge for incremental updates. |
|
||
| **SendToClientType** | Enum controlling broadcast scope: None, Others, Caller, All. |
|
||
|
||
## Logging
|
||
|
||
| Term | Definition |
|
||
|---|---|
|
||
| **AcLoggerBase** | Custom logger with Detail(0)→Debug(1)→Info(2)→Warning(3)→Suggest(4)→Error(5)→Disabled(255). Values are DB-synced — do not renumber. |
|
||
| **GlobalLogger** | Server-side singleton (`AcGlobalLogger`) for cross-service logging. |
|