ErisPulse ErisPulse
Open in interactive docs →
On this page
Static mirror — the interactive version is canonical Open in interactive docs →

Advanced Topics

This directory contains advanced topics of the ErisPulse framework—deep capabilities such as permission control, canary release, multi-round interaction, and storage backends—each addressing a specific category of problems.

Note

All topics in this directory are on-demand reference documents—please first read the five core L1 articles in the homepage, and then refer to this directory when encountering corresponding needs. Each article begins with a note indicating "When you need to read this article."

Four Essential L2 Articles

The following four articles are essential for writing production-grade modules. It is recommended to read them thoroughly before working on complex modules (consistent with the guidance on the documentation homepage):

  • Scope - Three-dimensional scope control: module availability / event access / outbound action restrictions (including method-level granular rules and binding inheritance merge)
  • Ownership (owner) System - Resource ownership and automatic cleanup: owner context mechanism, full view of owned resources, unload cleanup sequence, hot reload boundaries, and design boundaries
  • Lifecycle Management - Lifecycle event system: what each module / adapter should do when loading, unloading, reloading, or disabling
  • Interaction Session System - wait_reply / session timers / multi-path waiting / session mutual exclusion leases / inbox / message transactions / link tracing

Grouped by Scenario

The grouping follows the same criteria as the "Deep Understanding of Principles" section on the documentation homepage; the first article in each group notes "what pitfalls you'll hit without understanding it."

Running & Startup —— Without understanding the startup chain (Finder / Loader / Manager / Router), you can only stare helplessly at the logs when module loading fails.

Communication & Connection —— Without understanding the service contract (meta.services) whitelist, cross-module module.call calls will be rejected by ServiceNotProvidedError and you won't know why.

  • Inter-Module Communication - RPC protocolization (module.call), service contracts and directory, directed events, cold-start replay, and event idempotent deduplication
  • Connection Pools and Broadcasting - Connection registry: broadcasting, group subscription, cross-module passing and reuse, connection pool inspection
  • Router Manager - HTTP and WebSocket route management (including single-parameter registration and tuple response conventions)

Data Storage —— Without understanding the semantics of the connection-failure cooldown period, database instability will lead you to misjudge that "the framework is down" (in fact it fails fast and automatically reconnects after the cooldown).

  • Storage Backends - Selection, configuration, and switching of the sqlite / mysql / postgres async native storage backends
  • SQL Query Builder - A general-purpose SQL chained query builder and storage backend abstraction
  • Network Client - Unified HTTP request client

Messaging & Conversation —— Without understanding the conversation mutual-exclusion lease, two modules waiting for the same user's reply at the same time will kick each other off.

Shadow & Canary —— Promoting early without understanding the five isolation gates will let the shadow's outbound messages spill over to real users.

  • Shadow Modules and Canary Promotion - Independent-owner parallel trial runs of new module versions: outbound interception accounting, behavior diff comparison, promote-to-production, and rollback on failure

Performance & Observability —— If your only response to problems is restarting without looking at metrics, you're flying blind.

  • Performance Benchmarks and Tuning - Measured benchmark figures (including NoneBot2 comparisons), how to run benchmarks yourself and compare regressions, tuning essentials, and memory diagnostics
  • runtime Toolkit - Quick reference for the ErisPulse.runtime aggregated export layer: ownership, background tasks, event context, memory snapshots, dict parsing, and troubleshooting diagnostics

Exceptions & Standards Reference

Note

Documentation for third-party ecosystem modules such as Dashboard window registration and Takumi image rendering has been migrated to the Ecosystem Modules directory.

Intended Audience

These documents are suitable for the following types of developers:

  • Developers who are already familiar with the basic features of ErisPulse
  • Developers who need to deeply understand the internal mechanisms of the framework
  • Developers who need to optimize performance or implement complex features

Prerequisites

Before reading the documents in this directory, it is recommended to first understand: