alterator-backend-source

alterator-backend-source is Python module (CLI and API) for work with software sources based on Alterator Entry Source. The solution based on [apt-source], alterator-module-executor and alterator-backend-systeminfo.

Project Architecture

The project is strictly divided into two modules:

• api → domain logic and filesystem abstraction
• cli → user-facing command-line interface

High-level Dependency Diagram

          ┌────────────┐
          │    cli     │
          │ (commands) │
          └─────┬──────┘
                │
                ▼
        ┌───────────────────┐
        │ api.FrontDatabase │ ← central API object
        └─────┬─────┬───────┘
              │     │
              │     └──────────┐
              │                ▼
              │       ┌───────────────────┐
              │       │  mapper.to_list   │
              │       └──────┬────────────┘
              │              │
              ▼              ▼
    ┌────────────────────────────┐
    │ apt_source.api.Database    │
    └────────────────────────────┘

How It Works (Data Flow)

The module's operation centers on translating data from the Alterator Entry Source format into files that apt can understand.

Core Components

• api.FrontDatabase: facade class that provides high-level methods for working with sources. It composes apt_source.api.Database.
• api.mapper.to_list: inner translation module responsible for converting Alterator Entry Source structures into apt_source.api.Table entries.

sources.list File Generation

Based on the generated table, files are created in APT's effective sources.list.d directory as resolved from the runtime APT configuration, following these rules:

• For each mirror in the mirrors list → file: {name}__{mirror}.list
• For a local repository (local section) → file: {name}__local.list

Entry generation logic:

Component	Remote Mirrors	Local Repository
Type	rpm	rpm-dir with file:// based URI

Initial State: Disabled, unsigned. Architectures: Filtered based on current system architecture (via alterator-backend-systeminfo)

State Management

Information about the repository's active state is stored in the [state.active] section of the dynamical Alterator Entry Source itself. This should ensure synchronization runtime object's internal state according to sources.list files (runtime completeness).

Example of the dynamically generated section:

[state.active]
gpg = true
mirrors = ["ftp.altlinux.org"]
protocols = ["https"]
components = { classic = [ "x86_64", "noarch", "x86_64-i586" ], debuginfo = [ "x86_64" ] }

Field Semantics:

• gpg: This field is descriptive, not imperative. It automatically becomes true if and only if every active entry of this source in sources.list.d is signed with the key specified in gpg.name. If any .list entry is unsigned or signed with a different key, this field will be false. This provides a quick way to verify source integrity and validity.
• mirrors, protocols, components: Reflect the currently active set of mirrors, protocols, and components that are actually present in the sources.list files.

Synchronization Workflow

1. Initialization: api.FrontDatabase receives an Alterator Entry Source object. The mapper analyzes it and creates an internal representation (apt_source.api.Table).
2. File Generation: When the API changes the state of sources.list records, the [state.active] table is updated accordingly.
3. Invariant Maintenance: The invariant gpg == (all entries signed by gpg.name) is maintained automatically during all operations.
4. Saving Changes: All changes made in apt_source.api.Database using API are saved in file system. That is, sources.list files are updated, but not static .source files.

D-Bus Integration

The scripts/ folder contains scripts for generating .backend configuration files for alterator-module-executor from /usr/share/alterator/sources/ files. This is necessary for registering D-Bus objects at /org/altlinux/alterator/source_{name} that implement the interface described here. Each D-Bus object is a single source.

Installation

sudo apt-get install alterator-backend-source

Usage

Get inactive object description

$ busctl call \
          org.altlinux.alterator \
          /org/altlinux/alterator/source_alt_sisyphus \
          org.altlinux.alterator.source1 \
          Info
s "type = \"Source\"\nname = \"alt-sisyphus\"\n\ncategory = \"Alt\"\n\ndisplay_name.ru = \"\320\220\320\273\321\214\321\202 \320\233\320\270\320\275\321\203\320\272\321\201: \320\241\320\270\320\267\320\270\321\204\"\ndisplay_name.en = \"ALT Linux: Sisyphus\"\ncomment.ru = \"\320\240\320\265\320\263\321\203\320\273\321\217\321\200\320\275\320\260\321\217 \320\262\320\265\321\202\320\272\320\260\"\ncomment.en = \"Regular branch\"\n\nbranch.provides = \"sisyphus\"\n\ngpg.name = \"alt\"\ngpg.vendor = \"ALT Linux incominger <incominger@altlinux.org>\"\ngpg.fingerprint = \"49B01E70C64124E6742EAE7195C584D5AE4AE412\"\n\n\n[local]\npath = \"/run/media/sisyphus\"\n\n[mirrors.\"ftp.altlinux.org\"]\n\"/pub/distributions/ALTLinux/Sisyphus/\" = [\"http\", \"https\", \"ftp\"]\n\"/ALTLinux/Sisyphus/\" = [\"rsync\"]\n\n[mirrors.\"mirror.yandex.ru\"]\n\"/altlinux/Sisyphus\" = [ \"https\" ]\n\n[multiarch.\"x86_64-i586\"]\nbase_arch = \"x86_64\"\ndisplay_name.en = \"32-bit support\"\ncomment.en = \"...\"\n\n\n[components.classic]\ndisplay_name.en = \"classic\"\ncomment.en = \"classic\"\nhas_noarch = true\narch = [\n    \"x86_64\",\n    \"i586\",\n    \"aarch64\"\n]\nmultiarch = [ \"x86_64-i586\" ]\n\n[components.debuginfo]\ndisplay_name.en = \"debuginfo\"\ncomment.en = \"debuginfo\"\nrequires = \"classic\"\narch = [\"x86_64\"]\n\n[components.gostcrypto]\ndisplay_name.en = \"gostcrypto\"\ncomment.en = \"gostcrypto\"\nrequires = \"classic\"\narch = [\n    \"x86_64\",\n    \"i586\",\n    \"aarch64\"\n]\n\n[state.active]\nmirrors = []\nprotocols = []\n\n[state.active.components]\n"

Checking a mirror activation result (test running)

$ busctl call \
          org.altlinux.alterator \
          /org/altlinux/alterator/source_alt_sisyphus \
          org.altlinux.alterator.source1 \
          CheckApply "sasass" \
          "https://ftp.altlinux.org" \
          2 "classic" "debuginfo" \
          1 "x86_64-i586" \
          "alt"
asas 4 "rpm [alt] https://ftp.altlinux.org/pub/distributions/ALTLinux/Sisyphus/ x86_64 classic" "rpm [alt] https://ftp.altlinux.org/pub/distributions/ALTLinux/Sisyphus/ noarch classic" "rpm [alt] https://ftp.altlinux.org/pub/distributions/ALTLinux/Sisyphus/ x86_64-i586 classic" "rpm [alt] https://ftp.altlinux.org/pub/distributions/ALTLinux/Sisyphus/ x86_64 debuginfo" 0

Activate mirror with given components

$ busctl call \
          org.altlinux.alterator \
          /org/altlinux/alterator/source_alt_sisyphus \
          org.altlinux.alterator.source1 \
          Apply "sasass" \
          "https://ftp.altlinux.org" \
          2 "classic" "debuginfo" \
          1 "x86_64-i586" \
          "alt"

Get object description after activation

$ busctl call \
          org.altlinux.alterator \
          /org/altlinux/alterator/source_alt_sisyphus \
          org.altlinux.alterator.source1 \
          Info
s "type = \"Source\"\nname = \"alt-sisyphus\"\n\ncategory = \"Alt\"\n\ndisplay_name.ru = \"\320\220\320\273\321\214\321\202 \320\233\320\270\320\275\321\203\320\272\321\201: \320\241\320\270\320\267\320\270\321\204\"\ndisplay_name.en = \"ALT Linux: Sisyphus\"\ncomment.ru = \"\320\240\320\265\320\263\321\203\320\273\321\217\321\200\320\275\320\260\321\217 \320\262\320\265\321\202\320\272\320\260\"\ncomment.en = \"Regular branch\"\n\nbranch.provides = \"sisyphus\"\n\ngpg.name = \"alt\"\ngpg.vendor = \"ALT Linux incominger <incominger@altlinux.org>\"\ngpg.fingerprint = \"49B01E70C64124E6742EAE7195C584D5AE4AE412\"\n\n\n[local]\npath = \"/run/media/sisyphus\"\n\n[mirrors.\"ftp.altlinux.org\"]\n\"/pub/distributions/ALTLinux/Sisyphus/\" = [\"http\", \"https\", \"ftp\"]\n\"/ALTLinux/Sisyphus/\" = [\"rsync\"]\n\n[mirrors.\"mirror.yandex.ru\"]\n\"/altlinux/Sisyphus\" = [ \"https\" ]\n\n[multiarch.\"x86_64-i586\"]\nbase_arch = \"x86_64\"\ndisplay_name.en = \"32-bit support\"\ncomment.en = \"...\"\n\n\n[components.classic]\ndisplay_name.en = \"classic\"\ncomment.en = \"classic\"\nhas_noarch = true\narch = [\n    \"x86_64\",\n    \"i586\",\n    \"aarch64\"\n]\nmultiarch = [ \"x86_64-i586\" ]\n\n[components.debuginfo]\ndisplay_name.en = \"debuginfo\"\ncomment.en = \"debuginfo\"\nrequires = \"classic\"\narch = [\"x86_64\"]\n\n[components.gostcrypto]\ndisplay_name.en = \"gostcrypto\"\ncomment.en = \"gostcrypto\"\nrequires = \"classic\"\narch = [\n    \"x86_64\",\n    \"i586\",\n    \"aarch64\"\n]\n\n[state.active]\nmirrors = [\"ftp.altlinux.org\"]\nprotocols = [\"https\"]\ngpg = true\n\n[state.active.components]\nclassic = [\"x86_64\", \"noarch\", \"x86_64-i586\"]\ndebuginfo = [\"x86_64\"]\n"

Checking a source disabling

$ busctl call \
          org.altlinux.alterator \
          /org/altlinux/alterator/source_alt_sisyphus \
          org.altlinux.alterator.source1 \
          CheckApply "sasass" \
          "" \
          0 \
          0 \
          ""
asas 0 4 "rpm https://ftp.altlinux.org/pub/distributions/ALTLinux/Sisyphus/ x86_64 classic" "rpm https://ftp.altlinux.org/pub/distributions/ALTLinux/Sisyphus/ noarch classic" "rpm https://ftp.altlinux.org/pub/distributions/ALTLinux/Sisyphus/ x86_64-i586 classic" "rpm https://ftp.altlinux.org/pub/distributions/ALTLinux/Sisyphus/ x86_64 debuginfo"