Core Package Internals
Relevant source files
The following files were used as context for generating this wiki page:
The @onebots/core package functions as the central kernel of the OneBots framework. It provides the essential abstractions, registry systems, and runtime utilities required to facilitate multi-platform IM communication. The core manages the common lifecycle of adapters, protocols, and accounts, ensuring that raw platform events are normalized into a unified CommonEvent format before being exported to various wire protocols.
Key responsibilities of the core package include:
- Abstraction Layer: Defines base classes for
Adapter,Protocol, andAccount. - Infrastructure Services: Implements dependency injection, structured logging, and unified error handling.
- Runtime Management: Controls lifecycle hooks, resource cleanup, and observability via health probes and metrics.
- ID Mapping: Manages
createIdandresolveIdoperations to bridge platform-specific identifiers with internal standards.
Sources: AGENTS.md:14-25, packages/core/ARCHITECTURE.md:1-5
Dependency Injection and Service Management
The core utilizes a dedicated Dependency Injection (DI) container to manage service registration and resolution. This system allows the application to maintain singletons and resolve complex dependency graphs during initialization.
DI Container Logic
The Container class maintains a map of providers. It supports:
- Singleton Registration: Ensuring only one instance of a service exists.
- Dependency Resolution: Automatically providing required dependencies to constructors when a service is requested.
The diagram shows the flow from registering a singleton provider to resolving its dependencies and returning the instance.
Sources: packages/core/src/di-container.ts:1-35, packages/core/ARCHITECTURE.md:58-85
Lifecycle and Resource Management
The LifecycleManager coordinates the startup and shutdown phases of the application. It ensures that resources such as database connections, HTTP servers, and WebSocket gateways are initialized and cleaned up in the correct order.
Lifecycle Hooks
The system supports four primary hooks:
- onInit: Preparation phase for resources.
- onStart: Active phase where services begin processing.
- onStop: Graceful shutdown phase.
- onCleanup: Final resource release.
| Hook | Purpose | Execution Timing |
|---|---|---|
onInit | Initialize configuration and internal states | Before start() |
onStart | Start network listeners and timers | During start() |
onStop | Close listeners and stop accepting new requests | During stop() |
onCleanup | Destroy objects and free memory | After stop() |
Sources: packages/core/src/lifecycle.ts:1-50, packages/core/ARCHITECTURE.md:87-128
Unified Error Handling
The core implements a structured error hierarchy via errors.ts. This system categorizes failures to enable automated recovery logic and precise logging.
Error Categories
Errors are classified into the following types:
- NETWORK: Connection timeouts or DNS failures.
- CONFIG: Missing or invalid configuration parameters.
- RUNTIME: Unexpected execution failures.
- VALIDATION: Schema mismatch or data integrity issues.
- PROTOCOL/ADAPTER: Specific failures within the communication layers.
The ErrorHandler.wrap(error) method converts unknown exceptions into structured OneBotsError instances, retaining original context and stack traces.
Sources: packages/core/ARCHITECTURE.md:7-32, CONTRIBUTING.md:158-185
Observability and Metrics
The app-observability.ts module provides endpoints for monitoring the health and performance of the OneBots instance. It integrates with Prometheus for metric collection and provides readiness snapshots for deployment orchestrators.
Health and Readiness Endpoints
/health: Returns basic process identity, instance ID, and uptime./ready: Provides a detailed snapshot of account and protocol statuses. If any adapter is offline or protocols are unavailable, the readiness probe fails./metrics: Exports performance data, memory usage, and connection counts in Prometheus text format.
The sequence diagram illustrates how external monitors query health and metrics through the core router.
Sources: packages/core/src/app-observability.ts:74-138, packages/core/src/app-observability.ts:246-340
Reported Metric Types
| Metric Name | Type | Description |
|---|---|---|
onebots_uptime_seconds | Gauge | Total seconds since process start |
onebots_ready | Gauge | Binary status (1 for ready, 0 for not) |
onebots_memory_bytes | Gauge | Memory usage (RSS, heapTotal, heapUsed) |
onebots_accounts_total | Gauge | Count of accounts grouped by platform and status |
Sources: packages/core/src/app-observability.ts:275-325
Architecture and Data Flow
The core architecture follows a hierarchical structure where the BaseApp acts as the root container, managing multiple adapters.
This class diagram shows the containment relationship from the application level down to specific protocol instances.
Sources: architecture-diagrams.md:215-285, AGENTS.md:14-25
Summary
The internal mechanics of the @onebots/core package prioritize modularity and stability. By centralizing dependency injection, lifecycle control, and observability, it provides a robust foundation for building multi-platform bot services. The strict error handling and logging standards ensure that issues in individual adapters or protocols do not compromise the stability of the entire gateway process.
Sources: packages/core/ARCHITECTURE.md:145-155, AGENTS.md:8-12