Skip to main content
Version: v1.1

Common Infrastructure

Introduction​

AosCore components — Communication Manager (CM), Service Manager (SM), Identity and Access Manager (IAM), and Message Proxy (MP) — share a common infrastructure layer that provides reusable utilities and services. This shared code lives in two locations:

  • aos_core_cpp/src/common/ — application-level shared modules (cloud protocol, downloader, OCI spec, network, migration, logging, utilities)
  • aos_core_lib_cpp/src/core/common/ — platform-abstracted library interfaces (downloader, space allocator, OCI spec, logging, cloud connection, monitoring, alerts, crypto)

By centralizing these capabilities, AosCore avoids duplication across components and ensures consistent behavior for cross-cutting concerns like storage management, image handling, and protocol serialization.

Shared Modules Overview​

ModuleLocationPurposeUsed By
Cloud Protocolaos_core_cpp/src/common/cloudprotocol/JSON serialization/deserialization for the WebSocket cloud protocolCM
Downloaderaos_core_cpp/src/common/downloader/HTTP/HTTPS file download with retry, resume, and progress reportingSM, CM
OCI Specaos_core_cpp/src/common/ocispec/OCI image index, manifest, and config parsing/writingSM
Space Allocatoraos_core_lib_cpp/src/core/common/spaceallocator/Disk space management with partition-aware allocation and evictionSM, CM
Networkaos_core_cpp/src/common/network/Network interface management — bridges, VLANs, IP addressing, iptablesSM, CM
Migrationaos_core_cpp/src/common/migration/SQLite database schema migration with versioned scriptsCM, SM, IAM
Loggingaos_core_cpp/src/common/logging/Log archiving with compression for cloud transmissionSM, MP
File Serveraos_core_cpp/src/common/fileserver/HTTP file server for inter-component file distributionCM
Utilitiesaos_core_cpp/src/common/utils/Filesystem, gRPC helpers, JSON parsing, crypto, retry logic, timeAll

Cloud Protocol​

The cloudprotocol module implements JSON serialization and deserialization for all message types exchanged between CM and AosCloud over the WebSocket connection. It defines:

  • Message types — desiredStatus, unitStatus, alerts, monitoringData, requestLog, pushLog, provisioning messages, certificate messages, environment variable overrides, and more
  • Data structures — InstanceIdent, AosIdentity, Protocol version negotiation, error encoding
  • Serialization — bidirectional conversion between C++ types and Poco JSON objects

Each cloud protocol message category has its own source file (e.g., desiredstatus.cpp, alerts.cpp, monitoring.cpp, certificates.cpp), keeping the protocol implementation modular and maintainable.

Downloader​

The Downloader provides HTTP/HTTPS file retrieval with production-grade reliability features:

  • Retry with backoff — configurable retry count (default 3) with exponential delay (1s initial, 5s max)
  • Resume support — detects server range-request capability and resumes interrupted downloads
  • Progress reporting — periodic progress alerts sent through the alerts subsystem (configurable interval, default 30s)
  • Cancellation — per-digest cancellation support for aborting in-progress downloads
  • Local file copy — handles file:// URIs by direct filesystem copy

The Downloader is used by SM's Image Manager to retrieve service images and by CM for downloading Deployment Bundles from cloud-provided blob URLs.

For detailed documentation, see Downloader.

OCI Image Specification​

The ocispec module provides load/save operations for OCI (Open Container Initiative) image structures:

  • Image Index — the top-level manifest list pointing to platform-specific manifests
  • Image Manifest — references the config and layer blobs for a single image
  • Image Config — container configuration (environment, entrypoint, labels)
  • Item Config — AosEdge-specific metadata extending the OCI spec for Deployable Items
  • Runtime Config — OCI runtime specification for container execution

This module is the foundation for SM's image management pipeline — every service image downloaded and stored by AosCore is structured according to the OCI image specification.

For detailed documentation, see OCI Image Format.

Space Allocator​

The Space Allocator manages disk space across components that store persistent data (images, databases, logs). It provides:

  • Partition-aware allocation — tracks available space per filesystem mount point, shared across all allocators on the same partition
  • Percentage-based limits — each allocator can be configured with a maximum percentage of partition capacity
  • Automatic eviction — when space is exhausted, the allocator removes outdated items (oldest first) to free capacity
  • Concurrent allocation — thread-safe allocation with proper locking for multi-threaded components
  • Space lifecycle — allocated space can be accepted (committed), released (freed), or resized

SM uses the Space Allocator to manage storage for service images and layers. When new images arrive and storage is full, the allocator automatically evicts the oldest unused images to make room.

For detailed documentation, see Space Allocator.

Network Utilities​

The network module provides low-level network interface management used by both CM's and SM's network managers:

  • Interface Manager — creates and configures network interfaces (bridges, VLANs), manages IP addresses, and controls link state using netlink
  • Namespace Manager — manages Linux network namespaces for service isolation
  • IPTables — programmatic iptables rule management for traffic control and NAT
  • Utilities — IP address parsing, subnet calculation, and network helper functions

Database Migration​

The migration module provides versioned database schema management for all components that use SQLite storage (CM, SM, IAM):

  • Version tracking — maintains a version table in each database to track the current schema version
  • Forward migration — applies numbered migration scripts sequentially to upgrade the schema
  • Rollback support — supports downgrade migrations for safe version transitions
  • Script merging — merges migration files from a source directory into a consolidated migration directory

Each component initializes its database through the Migration class, ensuring the schema is always at the expected version before the component starts operating.

Logging Infrastructure​

The logging subsystem provides log collection and transmission capabilities:

  • Log Archiver (aos_core_cpp/src/common/logging/) — compresses log messages using deflate compression, splits them into size-limited parts, and sends them through the log sender interface for cloud transmission
  • Logging interfaces (aos_core_lib_cpp/src/core/common/logging/) — defines the platform-abstracted logging configuration and sender interfaces

General Utilities​

The utils module provides a broad set of helper functionality used across all components:

UtilityPurpose
filesystemFile and directory operations, path manipulation
fsplatformPlatform filesystem interface — mount point detection, size queries
fswatcherFilesystem change notification (inotify-based)
grpchelpergRPC channel creation, TLS credential setup
grpcclientcertlistenerAutomatic gRPC channel refresh on certificate rotation
grpcsubscriptionmanagerManages gRPC streaming subscriptions with reconnection
cryptohelperCertificate and key utility functions
jsonJSON parsing utilities (case-insensitive object wrapper)
retryGeneric retry logic with configurable backoff
timeTime formatting and conversion utilities
imageImage digest calculation and verification
cleanupmanagerDeferred cleanup registration for resource management
channelThread-safe communication channel (Go-style)
pk11uriPKCS#11 URI parsing for hardware security module access
pkcs11helperPKCS#11 token and key management utilities
syncmessagesenderSynchronous message sending with response waiting
exceptionException-to-error conversion utilities

Library-Level Interfaces​

The aos_core_lib_cpp/src/core/common/ layer provides platform-abstracted interfaces that the application-level modules implement:

ModulePurpose
downloader/itf/Download interface — allows platform-specific download implementations
spaceallocator/itf/Space allocation interface — partition and item management contracts
ocispec/itf/OCI spec interface — image structure load/save contracts
logging/itf/Log sender interface — platform-independent log transmission
cloudconnection/itf/Cloud connection interface — WebSocket abstraction
monitoring/Monitoring data collection interfaces
alerts/itf/Alert sender interface — component-independent alert dispatch
crypto/itf/Cryptographic operations interface — random, hashing, signing
iamclient/IAM client interface — certificate and identity access
pkcs11/PKCS#11 interface — hardware security module abstraction
types/Common type definitions shared across all modules
tools/Low-level utilities — static containers, memory, filesystem primitives

This two-layer design (interface in aos_core_lib_cpp, implementation in aos_core_cpp) enables unit testing with mock implementations and supports portability across different target platforms.