feat: add Extensions Manager

[pavelnikonorov]

Overview

An example extension definition file can be found in confido.ga4gh-sdk-extension.json. The Extensions Manager enables the application to load, manage, and enable extensions dynamically. Extensions can define methods, such as tls-verifier, to extend SDK functionality.

Extension Requirements

An extension's shared library must export an init function that:

1. Accepts the service and its extensions configuration as a JSON parameter (e.g., from ~/.ga4gh/config.json).
2. Returns a JSON object listing the extensible methods (e.g., tls-verifier).

Supported Extensible Methods

The SDK currently supports only the tls-verifier extensible method:

• The tls-verifier is used by the Transport struct to delegate SSL/TLS certificate verification.
• Each tls-verifier method is configurable through parameters such as:
  • security-mode: Accepts enforce (default) or permissive.
    • Enforce: Restricts API connections if verification fails.
    • Permissive: Allows connections even if verification fails, but performs verification.

Transport Struct Behavior

When one or more tls-verifier methods are enabled:

1. The Transport struct removes default built-in trusted certificates.
2. The verified certificate becomes the only certificate that the Transport's HTTP client accepts.
3. This ensures precise control over the certificates trusted by the application.

Dependencies

• Introduced dependencies such as libloading (for dynamic library handling) and base64 (for encoding/decoding).

[sourcery-ai]

Reviewer's Guide by Sourcery

This PR introduces an Extensions Manager system that enables dynamic loading and management of extensions in the GA4GH SDK. The implementation includes configuration handling, extension loading/unloading, and TLS verification capabilities. The changes primarily affect the configuration and transport layers, with additional CLI commands for extension management.

Sequence diagram for loading extensions

sequenceDiagram
    participant CLI
    participant Configuration
    participant ExtensionManager
    participant Extension
    CLI->>Configuration: from_file()
    Configuration->>ExtensionManager: new(installed_extensions, service_config)
    ExtensionManager->>Extension: new(config)
    Extension->>Extension: load(service_config)
    ExtensionManager-->>Configuration: ExtensionManager instance
    Configuration-->>CLI: Configuration instance

Loading

Class diagram for the new Extensions Manager

classDiagram
    class Configuration {
        +String base_path
        +Option<String> user_agent
        +Option<BasicAuth> basic_auth
        +Option<String> oauth_access_token
        +Option<String> bearer_access_token
        +Option<ApiKey> api_key
        +Option<ServiceExtensionsConfiguration> extensions
        +ExtensionManager extensions_manager
        +from_file(service_type: Option<ServiceType>, service_config_path: &String, extensions_config_path: &String) Result<Self, Box<dyn std::error::Error>>
    }

    class ExtensionManager {
        +Vec<Extension> extensions
        +new(installed_extensions: InstalledExtensions, service_config: Option<ServiceExtensionsConfiguration>) Result<Self, Box<dyn Error>>
        +get_extensions() &Vec<Extension>
        +lookup_extension_methods(unified_method_name: &str) Vec<&ExtensionMethod>
    }

    class Extension {
        +String name
        +String version
        +Option<String> path
        +Option<String> description
        +bool enabled
        +bool loaded
        +Option<Library> library
        +HashMap<String, Vec<ExtensionMethod>> methods
        +new(config: InstalledExtension) Result<Self, Box<dyn Error>>
        +load(service_config: Value)
    }

    class Transport {
        +Configuration config
        +reqwest::Client client
        +new(config: &Configuration) Result<Self, Box<dyn Error>>
    }

    Configuration --> ExtensionManager
    ExtensionManager --> Extension
    Transport --> Configuration

Loading

File-Level Changes

Change	Details	Files
Implemented an Extension Manager system for dynamic extension loading	Added ExtensionManager struct to handle extension lifecycle Created Extension struct to represent individual extensions Implemented methods for loading, enabling, and unloading extensions Added support for extension method lookup and invocation	lib/src/utils/extension_manager.rs lib/src/utils/extension.rs
Enhanced Configuration struct to support extensions	Added extension-related fields to Configuration struct Implemented serialization/deserialization for Configuration Added support for installed extensions configuration Created new structs for extension configuration	lib/src/utils/configuration.rs
Updated Transport layer to support TLS verification through extensions	Added TLS verification support using extension methods Implemented certificate handling for secure connections Added security mode support (enforce/permissive) Enhanced error handling and logging	lib/src/utils/transport.rs
Added CLI commands for extension management	Added extension subcommands (list, add, remove, enable) Updated main CLI structure to include extension commands Enhanced CLI documentation and help messages	cli/src/main.rs

Possibly linked issues

• Deploy Funnel #1: The PR implements the Extensions Manager, addressing the issue's requirement for extension support.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time. You can also use
  this command to specify where the summary should be inserted.

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.