feat(content-pipeline): Add Generals Online Integration with Full Content Pipeline Support

[undead2146]

🎯 Overview

This draft PR introduces comprehensive Generals Online integration into GenHub's content pipeline architecture, implementing a complete end-to-end flow from discovery through CAS storage. This PR is marked as DRAFT pending confirmation from the Generals Online development team regarding the final API endpoint specifications.

⚠️ Status: Awaiting feedback on API endpoints (manifest.json or latest.txt) from the Generals Online team.

---

🏗️ Architecture Overview

Content Pipeline Integration

GenHub's content pipeline follows a three-tier architecture for content acquisition:

1. Tier 3 (Orchestration): ContentOrchestrator coordinates all operations
2. Tier 2 (Provider): Provider manages the complete pipeline
3. Tier 1 (Pipeline): Specialized components handle discovery, resolution, and delivery

The Generals Online integration implements this pattern through four specialized pipeline components:

• GeneralsOnlineDiscoverer: Queries CDN API for available releases
• GeneralsOnlineResolver: Converts search results into content manifests
• GeneralsOnlineDeliverer: Downloads, extracts, and stores files in CAS
• GeneralsOnlineProvider: Orchestrates the complete acquisition flow

Dual Variants

Generals Online provides two game client variants (30Hz and 60Hz). The implementation creates two separate manifests during content delivery.

---

🔑 Key Features

1. API Discovery with Fallback Strategy

The discoverer implements a multi-tier API discovery approach:

Primary: manifest.json (full release metadata)
  ↓ (fallback)
Secondary: latest.txt (version string only)
  ↓ (fallback)
Tertiary: Mock release data (development)

This ensures GenHub can operate in three scenarios:

• Production: Full API available with size, hash, and changelog
• Partial API: Version-only polling for basic update detection
• Development: Mock data for testing before API deployment

2. Content-Addressable Storage Integration

All Generals Online files are stored in CAS with SHA-256 hashing:

• Deduplication: Shared files between variants stored once
• Integrity: Every file validated via cryptographic hash
• Efficiency: Only changed files downloaded during updates
• Isolation: Workspace strategies use hardlinks/symlinks to CAS

3. Automatic Update Detection

GeneralsOnlineUpdateService runs as a background service:

• Polls CDN every 24 hours (configurable via GeneralsOnlineConstants)
• Compares version strings using date + QFE number parsing
• Exposes IContentUpdateService for UI integration
• Provides version information to Downloads tab

4. Dependency Management

Manifests declare required dependencies:

• Base Game: Requires C&C Generals Zero Hour installation
• Minimum Version: Zero Hour 1.04 or later
• Validation: Automatic dependency resolution during profile launch

---

📦 Implementation Details

Core Components

Pipeline Components (GenHub/Features/Content/Services/GeneralsOnline/)

Component	Responsibility	Key Methods
GeneralsOnlineDiscoverer	CDN API querying and release discovery	DiscoverAsync() with 3-tier fallback
GeneralsOnlineResolver	Manifest creation from search results	ResolveAsync() using manifest factory
GeneralsOnlineDeliverer	ZIP download, extraction, CAS storage	DeliverContentAsync() with dual manifest creation
GeneralsOnlineProvider	End-to-end orchestration	PrepareContentAsync() coordinating full pipeline
GeneralsOnlineManifestFactory	Manifest generation for variants	CreateManifests(), UpdateManifestsWithExtractedFiles()
GeneralsOnlineUpdateService	Background update checking	CheckForUpdatesAsync() with 24hr polling

Data Models (GenHub.Core/Models/GeneralsOnline/)

Model	Purpose
GeneralsOnlineRelease	Release metadata (version, URLs, size, changelog)
GeneralsOnlineApiResponse	API deserialization for manifest.json

Constants (GenHub.Core/Constants/GeneralsOnlineConstants.cs)

Centralized configuration including:

• API Endpoints: ManifestApiUrl, LatestVersionUrl, CdnBaseUrl
• Web URLs: WebsiteUrl, DownloadPageUrl, SupportUrl
• Metadata: PublisherName, ContentName, Description, Tags
• Update Intervals: UpdateCheckIntervalHours (default: 24)
• Variant Identifiers: Variant30HzSuffix, Variant60HzSuffix

---

🔄 Content Acquisition Flow

User Experience Flow

graph TB
    A[User clicks Install in Downloads Tab] --> B[Discovery Phase]
    B --> C{API Available?}
    C -->|Yes| D[Query manifest.json]
    C -->|Partial| E[Query latest.txt]
    C -->|No| F[Use Mock Data]
    D --> G[Resolution Phase]
    E --> G
    F --> G
    G --> H[Create Dual Manifests 30Hz/60Hz]
    H --> I[Delivery Phase]
    I --> J[Download ZIP Package]
    J --> K[Extract to Temporary Directory]
    K --> L[Compute SHA-256 Hashes]
    L --> M[Store Files in CAS]
    M --> N[Register Both Manifests in Pool]
    N --> O[User Selects Variant in Profile]
    O --> P[Workspace Links from CAS]
    P --> Q[Game Launch]

Loading

Technical Pipeline Flow

1. Discovery: GeneralsOnlineDiscoverer.DiscoverAsync()

   • Queries CDN endpoints with fallback strategy
   • Creates ContentSearchResult with GeneralsOnlineRelease metadata

2. Resolution: GeneralsOnlineResolver.ResolveAsync()

   • Calls GeneralsOnlineManifestFactory.CreateManifests()
   • Returns primary (30Hz) manifest for orchestrator

3. Delivery: GeneralsOnlineDeliverer.DeliverContentAsync()

   • Downloads ZIP via IDownloadService
   • Extracts to temporary directory
   • Calls UpdateManifestsWithExtractedFiles() to compute hashes
   • Stores both manifests via IContentManifestPool.AddManifestAsync()
   • Files automatically transferred to CAS during pool registration

4. Profile Integration: User workflow

   • Both variants appear in "Available Game Clients" in profile editor
   • User selects preferred variant (30Hz or 60Hz)
   • Workspace strategy creates links from CAS to workspace directory
   • Launch uses selected variant's executable

---

API Endpoint Specifications (PENDING REVIEW)

Current Implementation

The implementation supports two API endpoints:

Primary Endpoint: manifest.json

URL: https://cdn.playgenerals.online/manifest.json

Expected Response Format:

{
  "version": "101525_QFE5",
  "download_url": "https://cdn.playgenerals.online/releases/GeneralsOnline_portable_101525_QFE5.zip",
  "size": 38000000,
  "release_notes": "QFE5 Release - Improved stability and networking performance",
  "sha256": "abcd1234..." 
}

Secondary Endpoint: latest.txt

URL: https://cdn.playgenerals.online/latest.txt

Expected Response Format:

101525_QFE5

Questions for Generals Online

Download URL Pattern: Is the constructed URL pattern correct?

https://cdn.playgenerals.online/releases/GeneralsOnline_portable_{VERSION}.zip

Version Format: Confirm version format is MMDDYY_QFE# (e.g., 101525_QFE5)
SHA-256 Hashes: Will manifest.json include SHA-256 hash of the ZIP file?
Update Frequency: Is 24-hour update check interval appropriate?
Additional Metadata: Any additional fields needed in manifest.json?

---

🔧 Infrastructure Changes

Dependency Injection Registration

File: ContentPipelineModule.cs

Added registrations for:

• GeneralsOnlineProvider as IContentProvider
• GeneralsOnlineDiscoverer as IContentDiscoverer
• GeneralsOnlineResolver as IContentResolver
• GeneralsOnlineDeliverer as IContentDeliverer
• GeneralsOnlineUpdateService as IHostedService and IContentUpdateService

CAS Integration Enhancements

Files Modified:

• ContentStorageService.cs: CAS-aware file storage
• ContentValidator.cs: CAS existence validation
• WindowsFileOperationsService.cs: CAS-based linking

Key Enhancement: Storage service now recognizes ContentSourceType.ContentAddressable and routes files to CAS instead of manifest-specific directories.

Game Client Hash Registry

File: GameClientHashRegistry.cs

Added hash entries for Generals Online executables:

• generalsonline_30hz.exe: 30Hz client
• generalsonline_60hz.exe: 60Hz client
• GeneralsOnlineLauncher.exe: Updater/launcher

This enables client version detection and integrity validation.

---

🎨 UI Integration

Downloads Tab Enhancement

File: DownloadsView.axaml

Added "Generals Online" installation button with:

• Real-time version display
• Installation progress bar
• Status messages during acquisition
• Update availability indicator

ViewModel: DownloadsViewModel.cs

New features:

• InstallGeneralsOnlineCommand: Triggers content pipeline
• CheckGeneralsOnlineVersionAsync(): Queries update service
• Progress reporting via ContentAcquisitionProgress

Profile Editor Integration

File: ProfileContentLoader.cs

Enhanced to load CAS-stored game clients:

• Scans ContentManifestPool for ContentType.GameClient
• Displays both Generals Online variants as selectable options
• Supports mixed sources (installation-based + CAS-stored)

---

📝 Documentation Updates

Added Documentation

• GeneralsOnlineConstants.cs: 67 comprehensive documentation comments
• README.md: Complete provider overview and architecture explanation
• Flow Diagrams: End-to-end acquisition flow documentation
• API Specification: Endpoint documentation for Generals Online team

Updated Documentation

• architecture.md: Content pipeline architecture section
• constants.md: GeneralsOnlineConstants reference
• constants.md: API endpoint specifications

Draft Status: This PR is ready for architectural review but awaits final API endpoint confirmation from the Generals Online development team before merging.