Version Control of Packages

This document explains how the package version control system works in Helium, ensuring purchased packages remain consistent while allowing marketing teams to update offerings. This is essential for maintaining service reliability and customer trust.

The Concept of Packages

A package is the fundamental service offering unit that defines what a user receives when they purchase a production. Each package contains:

• Traffic Limit: Maximum data transfer allowed (in bytes)
• Max Client Number: Maximum simultaneous client connections
• Expire Duration: How long the package remains valid after activation
• Available Group: Access control group determining which proxy nodes are accessible
• Version: Version number for tracking changes

Packages are organized into Package Series - logical groupings identified by UUID that contain multiple versions of the same offering. When a user purchases a production, they receive a package from the associated series.

pub struct Package {
    pub id: i64,
    pub series: Uuid,           // Groups related packages
    pub version: i32,           // Version within the series
    pub is_master: bool,        // Currently delivered version
    pub available_group: i32,   // Access control group
    pub max_client_number: i32, // Connection limit
    pub expire_duration: PgInterval, // Validity period
    pub traffic_limit: i64,     // Data transfer limit
}

Version Control System

The version control system ensures package stability for users while enabling content updates for marketing. The core principle is:

Production always delivers the master version of a package series

Master Package Concept

Within each package series, exactly one package is marked as is_master = true. This is the version that:

• Gets delivered to users when they purchase a production
• Appears in production listings and user interfaces
• Represents the current “live” offering

-- Finding the master package for a series
SELECT * FROM "telecom"."packages"
WHERE series = $1 AND is_master = TRUE
LIMIT 1

Version Control Benefits

1. User Protection: Once a user purchases a package, their service parameters never change unexpectedly
2. Marketing Flexibility: Marketing can update package contents by creating new versions
3. Rollback Capability: Previous versions remain available for troubleshooting or rollbacks
4. Audit Trail: Complete history of package changes through version tracking

Two Types of Editing Operations

The system supports two distinct editing patterns depending on the impact and intent:

Create New Version (Version-Changing Edit)

When to use: When making changes that affect the core service offering or user experience.

Use cases:

• Changing traffic limits or client connection limits
• Modifying expire duration
• Updating available proxy groups
• Any change that affects what users receive

Process:

1. Create a new package in the same series with incremented version
2. Set the new package as is_master = true
3. Set the previous master as is_master = false
4. New purchases will receive the new version
5. Existing users keep their original package version

Example:

-- Old master: series=uuid-123, version=1, is_master=true, traffic_limit=100GB
-- New master: series=uuid-123, version=2, is_master=true, traffic_limit=200GB

Update Without Version Change (Non-Version Edit)

When to use: When making changes that don’t affect core functionality or user experience.

Use cases:

• Internal metadata updates
• Performance optimizations that don’t change user-visible behavior
• Bug fixes that don’t alter service parameters
• Administrative flags or internal tracking data

Process:

1. Directly update the existing package record
2. Version number remains unchanged
3. is_master status remains unchanged
4. Changes may affect both new and existing users (use carefully)

Example:

-- Update internal flags without affecting service delivery
UPDATE "telecom"."packages"
SET internal_metadata = $1
WHERE id = $2

Decision Matrix

Admin Capabilities

Administrators have several tools for managing packages and the version control system:

Package Queue Management

Admins can directly manage user package assignments:

• Add Queued Package: Assign specific packages to users
• Cancel Queued Package: Remove packages from user queues
• List/Count Queued Packages: Monitor package distribution

pub struct AdminAddQueuedPackage {
    pub user_id: Uuid,
    pub package_id: i64,      // Direct package ID, not series
    pub by_order: Option<Uuid>, // Optional order reference
}

Production Management

Admins control the production catalog that references package series:

• Create Production: Define new offerings linked to package series
• Delete Production: Remove offerings from the market
• View Production Details: See master package information

pub struct AdminCreateProduction {
    pub package_series: Uuid,    // References the series
    pub package_amount: i32,     // Number of packages to deliver
    // ... other production fields
}

Version Control Operations

Current Limitations: The codebase shows that direct package creation/editing APIs are not yet implemented in the admin interface. Package management currently happens at the database level.

Typical Admin Workflow:

1. Create new package versions via database operations
2. Update is_master flags to promote new versions
3. Create/update productions to reference package series
4. Monitor package queues and user assignments

Admin Roles and Permissions

Different admin roles have different package management capabilities:

• SuperAdmin: Full access to all package operations
• Moderator: Can manage package queues and productions
• CustomerSupport: Can add/cancel user packages for support purposes

Best Practices

1. Always use version changes for user-facing modifications
2. Test new package versions before setting as master
3. Maintain clear version history with meaningful version increments
4. Monitor user impact when promoting new package versions
5. Keep rollback capability by preserving previous versions
6. Document version changes for team coordination

Technical Integration

Database Schema

-- Package series grouping
CREATE TABLE "telecom"."package_series" (
    id UUID PRIMARY KEY
);

-- Individual packages with version control
CREATE TABLE "telecom"."packages" (
    id BIGSERIAL PRIMARY KEY,
    series UUID REFERENCES "telecom"."package_series"(id),
    version INTEGER NOT NULL,
    is_master BOOLEAN NOT NULL DEFAULT FALSE,
    -- ... service parameters
    UNIQUE(series, version)
);

Key Queries

-- Get current master package for a series
SELECT * FROM packages WHERE series = ? AND is_master = TRUE;

-- Promote a package to master (transaction required)
BEGIN;
UPDATE packages SET is_master = FALSE WHERE series = ?;
UPDATE packages SET is_master = TRUE WHERE id = ?;
COMMIT;

This version control system ensures that the platform can evolve its offerings while maintaining service consistency for existing users, providing both stability and flexibility for business operations.