mkdocs.yml

site_name: Nalix
site_description: Enterprise-grade real-time TCP networking framework for .NET
site_url: https://ppn.io.vn/
copyright: Copyright © 2025-2026 PPN Corporation
repo_url: https://github.com/ppn-systems/nalix
repo_name: nalix
edit_uri: https://github.com/ppn-systems/nalix/edit/master/docs/

extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/ppn-systems/nalix
    - icon: fontawesome/brands/facebook
      link: https://facebook.com/ppn.system
  announcement: |
    🚀 Nalix is under active development. Star us on GitHub!
  canonical_url: https://ppn.io.vn/
  meta:
    - name: keywords
      content: real-time server, .NET, networking, TCP, UDP
    - property: og:type
      content: website
    - property: og:title
      content: Nalix Documentation
    - property: og:description
      content: High-performance real-time server framework for .NET
  analytics:
    provider: google
    property: G-1MR49ERG6K

theme:
  name: material
  custom_dir: docs/overrides
  language: en
  logo: assets/nalix.png
  favicon: assets/nalix.ico
  # font:
  #   text: Inter
  #   code: "JetBrains Mono"
  font: false
  palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: white
      accent: indigo
      toggle:
        icon: material/weather-night
        name: Switch to dark mode

    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: black
      accent: indigo
      toggle:
        icon: material/weather-sunny
        name: Switch to light mode
  features:
    - navigation.path
    - navigation.tabs
    - navigation.top
    - navigation.instant
    # - navigation.instant.prefetch
    - navigation.tabs.sticky
    # - navigation.sections
    - header.sticky
    - search.highlight
    - search.suggest 
    - content.action.edit
    - content.action.view
    - content.tabs
    - content.code.copy
    - content.code.annotate
    - content.tooltips

plugins:
  - search:
      separator: '[\s\-\.]+'
  # - social
  - git-revision-date-localized:
      type: datetime
      enable_creation_date: true
      fallback_to_build_date: true
      enable_git_follow: false
  - mermaid2

markdown_extensions:
  - md_in_html
  - admonition
  - pymdownx.details
  - attr_list
  - pymdownx.highlight:
      guess_lang: false
      use_pygments: true
      anchor_linenums: true
      pygments_lang_class: true
      line_spans: __span
  - toc:
      permalink: true
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:mermaid2.fence_mermaid_custom
  - pymdownx.inlinehilite
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - pymdownx.betterem:
      smart_enable: all
  - pymdownx.tabbed:
      alternate_style: true

extra_css:
  - stylesheets/extra.css

nav:
  - Overview: index.md
  - Start Here:
      - Quick Start: quickstart.md
      - Installation: installation.md
      - Your First Server: guides/getting-started/your-first-server.md
  - Guides:
      - Overview: guides/index.md
      - Build a Chat Room: guides/build-a-chat-room.md
      - Securing Your Server: guides/securing-your-server.md
      - Application Logic:
          - Implementing Packet Handlers: guides/application/packet-handlers.md
          - Middleware Usage Guide: guides/application/middleware-usage.md
      - Networking:
          - Client Session Guide: guides/networking/connecting-clients.md
          - UDP Server Guide: guides/networking/udp-server.md
          - TCP Patterns Guide: guides/networking/tcp-patterns.md
          - UDP Security Guide: guides/networking/udp-security.md
          - Idle Connection Timeout: guides/networking/idle-timeout-configuration.md
      - Extensibility:
          - Custom Middleware Guide: guides/extensibility/custom-middleware.md
          - Custom Packet Router: guides/extensibility/custom-packet-router.md
          - Custom Metadata Providers: guides/extensibility/metadata-providers.md
          - Custom Serialization Provider: guides/extensibility/serialization-providers.md
      - Getting Started References:
          - Server Blueprint: guides/getting-started/server-blueprint.md
      - Deployment & Operations:
          - Production Checklist: guides/deployment/production-checklist.md
          - Reverse Proxy TLS (nginx / Caddy): guides/deployment/reverse-proxy-tls.md
          - Troubleshooting Guide: guides/deployment/troubleshooting.md
  - Concepts:
      - Overview: concepts/index.md
      - How Packets Work: concepts/how-packets-work.md
      - Handlers and Middleware: concepts/handlers-and-middleware.md
      - Configuration: concepts/configuration.md
      - Hosting Model: concepts/application/hosting-model.md
      - Glossary: concepts/glossary.md
      - Internals:
          - Overview: concepts/internals/index.md
          - Architecture: concepts/internals/architecture.md
          - Packet Lifecycle: concepts/internals/packet-lifecycle.md
          - Errors and Diagnostics: concepts/internals/errors-and-diagnostics.md
          - Binary Specification: concepts/internals/binary-spec.md
          - Real-time Engine: concepts/internals/real-time-engine.md
          - Middleware Pipeline: concepts/internals/middleware-pipeline.md
          - Configuration System: concepts/internals/configuration.md
          - Security Architecture: concepts/internals/security-architecture.md
          - Encryption Model: concepts/internals/encryption-model.md
          - Handshake Protocol: concepts/internals/handshake-protocol.md
          - Session Resumption: concepts/internals/session-resumption.md
          - Sharding & Concurrency: concepts/internals/sharding.md
          - Zero-Allocation Path: concepts/internals/zero-allocation.md
          - Guarantees and Failure Handling: concepts/internals/guarantees-and-failure-handling.md
          - Design Tradeoffs: concepts/internals/design-tradeoffs.md
          - Performance Optimizations: concepts/internals/performance-optimizations.md
          - Advanced Guides:
              - Manual Wiring (No Hosting): concepts/internals/minimal-server.md
              - Low-Level Session APIs: concepts/internals/low-level-session-apis.md
              - BufferLease Utilization: concepts/internals/buffer-lease-utilization.md
              - Buffer Pooling Configuration: concepts/internals/buffer-pooling-configuration.md
  - Packages:
      - Overview: packages/index.md
      - Nalix.Abstractions: packages/nalix-abstractions.md
      - Nalix.Environment: packages/nalix-environment.md
      - Nalix.Codec: packages/nalix-codec.md
      - Nalix.Framework: packages/nalix-framework.md
      - Nalix.Network: packages/nalix-network.md
      - Nalix.Runtime: packages/nalix-runtime.md
      - Nalix.Hosting: packages/nalix-hosting.md
      - Nalix.SDK: packages/nalix-sdk.md
  - API:
      - Overview: api/index.md
      - Analyzers:
        - Overview: api/analyzers/index.md
        - Diagnostic Codes: api/analyzers/diagnostic-codes.md
        - Code Fixes: api/analyzers/code-fixes.md
        - Generators:
          - Overview: api/analyzers/autogen/index.md
          - Packet Handler: api/analyzers/autogen/packet-handler-generator.md
          - Instance: api/analyzers/autogen/instance-generator.md
          - Serialization: api/analyzers/autogen/serialization-generator.md
          - Packet Registry: api/analyzers/autogen/packet-registry-generator.md
          - Packet Schema: api/analyzers/autogen/packet-schema-generator.md
          - Configuration: api/analyzers/autogen/configuration-generator.md
      - Abstractions:
        - Overview: api/abstractions/index.md
        - Control Type: api/abstractions/protocols/control-type.md
        - Packet Contracts: api/abstractions/packet-contracts.md
        - Connection Contracts: api/abstractions/connection-contracts.md
        - Session Contracts: api/abstractions/session-contracts.md
        - Concurrency Contracts: api/abstractions/concurrency-contracts.md
        - Packet Attributes: api/abstractions/packet-attributes.md
        - Packet Metadata: api/abstractions/packet-metadata.md
        - Enums: api/abstractions/enums.md
        - Validation Attributes: api/abstractions/validation.md
        - Injection Attributes: api/abstractions/injection.md
      - Framework:
        - Overview: api/framework/index.md
        - Environment:
          - Overview: api/environment/index.md
          - Directories: api/environment/directories.md
          - Clock: api/environment/clock.md
          - Random: api/environment/random.md
          - Timing Scope: api/environment/timing-scope.md
          - Configuration: api/environment/configuration.md
          - Sequencing: api/environment/sequencing.md
          - Memory:
            - Buffer Management: api/environment/memory/buffer-management.md
            - BufferLease: api/environment/memory/buffer-lease.md
            - DataReader: api/environment/memory/data-reader.md
            - DataWriter: api/environment/memory/data-writer.md
        - Runtime:
          - Snowflake: api/framework/snowflake.md
          - Task Manager: api/framework/task-manager.md
          - Singleton Base: api/framework/singleton-base.md
          - Instance Manager (DI): api/framework/instance-manager.md
        - Options:
          - Worker Options: api/framework/options/worker-options.md
          - Recurring Options: api/framework/options/recurring-options.md
        - Memory:
          - Object Pooling: api/framework/memory/object-pooling.md
          - Object Map: api/framework/memory/object-map.md
          - Typed Object Pools: api/framework/memory/typed-object-pools.md
        - Codec:
          - Overview: api/codec/index.md
          - LZ4: api/codec/lz4.md
          - Frame Pipeline: api/codec/frame-pipeline.md

          - Packets:
            - Frame Model: api/codec/packets/frame-model.md
            - Fragmentation: api/codec/packets/fragmentation.md
            - Built-in Frames: api/codec/packets/built-in-frames.md
            - Packet Registry: api/codec/packets/packet-registry.md
          - Serialization:
            - Serialization Basics: api/codec/serialization/serialization-basics.md
            - Packet Serialization: api/codec/serialization/packet-serialization.md
            - Attributes: api/abstractions/serialization-attributes.md
            - IO & Headers: api/codec/serialization/reader-writer-and-header-extensions.md
        - Memory & Pooling:
          - Packet Pooling: api/runtime/pooling/packet-pooling.md
          - Object Pooling: api/framework/memory/object-pooling.md
          - Object Map: api/framework/memory/object-map.md
          - Typed Object Pools: api/framework/memory/typed-object-pools.md
      - Cryptography:
        - Overview: api/security/cryptography.md
        - Hashing and MAC: api/security/hashing-and-mac.md
        - AEAD and Envelope: api/security/aead-and-envelope.md
        - Key Exchange: api/security/key-exchange.md
        - Handshake Protocol: api/security/handshake.md
        - Session Resume: api/security/session-resume.md
        - Session Rekey: api/security/session-rekey.md
        - Proof-of-Work: api/security/proof-of-work.md
        - Permission Levels: api/security/permission-level.md
      - Runtime:
        - Overview: api/runtime/index.md
        - Handlers: api/runtime/handlers/index.md
        - Routing:
          - Overview: api/runtime/routing/index.md
          - Context: api/runtime/routing/packet-context.md
          - Packet Sender: api/runtime/routing/packet-sender.md
          - Dispatch Contracts: api/runtime/routing/dispatch-contracts.md
          - Dispatch: api/runtime/routing/packet-dispatch.md
          - Dispatch Channel and Router: api/runtime/routing/dispatch-channel-and-router.md
          - Handler Return Types: api/runtime/routing/handler-results.md
        - Middleware:
          - Overview: api/runtime/middleware/index.md
          - Pipeline: api/runtime/middleware/pipeline.md
          - Policy Rate Limiter: api/runtime/middleware/policy-rate-limiter.md
          - Token Bucket Limiter: api/runtime/middleware/token-bucket-limiter.md
          - Permission Middleware: api/runtime/middleware/permission-middleware.md
          - Timeout Middleware: api/runtime/middleware/timeout-middleware.md
      - Network:
        - Overview: api/network/index.md
        - Protocol: api/network/protocol.md
        - TCP Listener: api/network/tcp-listener.md
        - UDP Listener: api/network/udp-listener.md
        - WebSocket Listener: api/network/websocket-listener.md
        - Socket Connection: api/network/socket-connection.md
        - WebSocket Connection: api/network/websocket-connection.md
        - Session Store: api/network/session-store.md
        - Connection:
          - Overview: api/network/connection/connection.md
          - Hub: api/network/connection/connection-hub.md
          - Events: api/network/connection/connection-events.md
          - Extensions: api/network/connection/connection-extensions.md
          - Limiter: api/network/connection/connection-limiter.md
          - Guard: api/network/connection/connection-guard.md
        - Time:
          - Time Synchronizer: api/network/time/time-synchronizer.md
          - Timing Wheel: api/network/time/timing-wheel.md
      - Hosting:
        - Application: api/hosting/network-application.md
        - WebSocket Binding: api/hosting/websocket-binding.md
      - SDK:
        - Overview: api/sdk/index.md
        - High-level APIs:
          - TCP Session: api/sdk/tcp-session.md
          - UDP Session: api/sdk/udp-session.md
          - WebSocket Session: api/sdk/websocket-session.md
          - Handshake Extensions: api/sdk/handshake-extensions.md
          - Resume Extensions: api/sdk/resume-extensions.md
          - Session Extensions: api/sdk/tcp-session-extensions.md
          - Cipher Updates: api/sdk/cipher-extensions.md
          - Control Utilities: api/sdk/control-utilities.md
          - Session Diagnostics: api/sdk/diagnostics.md
          - Session Subscriptions: api/sdk/subscriptions.md
        - Low-level Primitives:
          - Thread Dispatching: api/sdk/thread-dispatching.md
          - Frame Reader and Sender: api/sdk/frame-reader-and-sender.md
          - Transport Session: api/sdk/transport-session.md
          - Protocol String Extensions: api/sdk/protocol-string-extensions.md
      - Options:
        - Runtime:
          - Packet Dispatch Options: api/options/runtime/packet-dispatch-options.md
          - Dispatch Options: api/options/runtime/dispatch-options.md
        - Network:
          - Overview: api/options/network/options.md
          - Network Socket: api/options/network/network-socket-options.md
          - Connection Quota: api/options/network/connection-quota-options.md
          - Connection Guard: api/options/network/connection-guard-options.md
          - Connection Ban Store: api/options/network/connection-ban-store-options.md
          - Connection Blacklist Store: api/options/network/connection-blacklist-store-options.md
          - Trusted Proxy: api/options/network/trusted-proxy-options.md
          - Proxy Protocol: api/options/network/proxy-protocol-options.md
          - Connection Hub: api/options/network/connection-hub-options.md
          - WebSocket Transport: api/options/network/websocket-options.md
          - Datagram Guard: api/options/network/datagram-guard-options.md
          - Timing Wheel: api/options/network/timing-wheel-options.md
          - Pooling: api/options/network/pooling-options.md
          - Network Callback: api/options/network/network-callback-options.md
          - Session Store: api/options/network/session-store-options.md
          - Compression: api/options/network/compression-options.md
          - Token Bucket: api/options/network/token-bucket-options.md
          - Directive Guard: api/options/network/directive-guard-options.md
        - Hosting: api/options/hosting/hosting-options.md
        - SDK:
          - Transport Options: api/options/sdk/transport-options.md
          - WebSocket Transport: api/options/sdk/websocket-transport-options.md
          - Request Options: api/options/sdk/request-options.md
  - Benchmarks:
      - Overview: benchmarks/index.md
      - Core Infrastructure: benchmarks/infrastructure.md
      - Memory & Storage: benchmarks/memory.md
      - Data Processing: benchmarks/data-processing.md
      - Security & Cryptography: benchmarks/security.md
      - Serialization: benchmarks/serialization.md
      - Serialization Method Comparison: benchmarks/serialization-method-compare.md