Migrating CLI To Provenance Gateway: A Step-by-Step Guide

by Alex Johnson 58 views

Introduction: The Shift to Provenance Gateway

In the ever-evolving landscape of decentralized storage, adapting to new technologies and services is crucial. This article delves into the process of migrating the Command Line Interface (CLI) to leverage the provenance-gateway.datafund.io API as its primary backend. This migration represents a significant step towards enhancing the CLI's functionality, reliability, and user experience. By shifting the default backend to the gateway, we can harness its advanced features while still offering the flexibility to interact with local Bee nodes. This guide provides a detailed roadmap, covering the current state, target state, migration strategy, implementation tasks, and testing procedures involved in this transition. This ensures a comprehensive understanding for developers and users alike. Let's explore how we can successfully migrate CLI to use provenance-gateway.datafund.io as default backend for a more robust and feature-rich experience. This transition is not merely a change of backend, but also a move towards a more sustainable and user-friendly interaction with the swarm network.

Understanding the Current State of the CLI

Currently, the CLI directly communicates with a Bee node. The CLI uses several endpoints for different operations, such as purchasing stamps, uploading and downloading data. These interactions are fundamental to how users interact with the swarm network through the CLI. Understanding these interactions is essential to migrate CLI to use provenance-gateway.datafund.io as default backend. The existing endpoints include:

  • POST /stamps/{amount}/{depth}: Used for purchasing stamps, which are essential for data storage. These stamps are critical for guaranteeing the permanence of data stored on the swarm network.
  • GET /stamps/{id}: Used to retrieve information about a specific stamp using its unique identifier.
  • POST /bzz: Used for uploading data to the swarm network. This allows users to store files and other data in a decentralized manner.
  • GET /bzz/{ref}: Used for downloading data from the swarm network using its reference hash.

These API calls are the backbone of the CLI's interaction with the swarm network. Therefore, the migration strategy must consider the functionality and the impact on the existing user workflow. So that it will be a smooth transition for all users.

The Target State: Embracing the Provenance Gateway

The target state involves transitioning the CLI to utilize the provenance-gateway.datafund.io API. This transition brings several benefits, including enhanced features and improved reliability. The migration to the gateway API necessitates a shift in how the CLI interacts with the swarm network. This involves changing the endpoints used for various operations and adding new functionalities. The OpenAPI specification for the gateway API, available at /api/v1/openapi.json, serves as a guide for these changes. The transition to the provenance gateway will enhance the CLI's functionalities and provide a more robust experience. The new endpoints are:

  • POST /api/v1/stamps/: Purchases stamps, with the request body replacing the URL parameters.
  • GET /api/v1/stamps/{id}: Retrieves information about a stamp.
  • PATCH /api/v1/stamps/{id}/extend: Extends the validity of a stamp, a new feature.
  • POST /api/v1/data/: Uploads data using a multipart form, providing greater flexibility.
  • GET /api/v1/data/{ref}: Downloads data from the network.
  • GET /api/v1/data/{ref}/json: Downloads data with associated metadata, another new feature.

These new endpoints and features highlight the enhanced capabilities of the provenance gateway, making it an ideal choice for the CLI's backend.

Migration Strategy: A Phased Approach

To ensure a smooth transition, the migration will be implemented in phases, providing flexibility and minimizing disruption. This structured approach allows developers to address any issues and gradually introduce new features while maintaining the usability of the CLI. The phased strategy is designed to balance introducing new features with ensuring the continued usability of the CLI.

Phase 1: Dual Backend Support

The first phase focuses on introducing dual backend support. This means that users can choose between the gateway and a local Bee node. This flexibility will allow users to adapt to the new gateway while also using the current local Bee node. This phase is critical because it offers a safety net for users and facilitates testing and refinement of the gateway integration. Key elements of this phase include:

  • --backend Flag: A new flag will be added to the CLI, allowing users to specify the backend they wish to use. The default value will be gateway, directing the CLI to use the provenance-gateway.datafund.io API.
  • Gateway URL: The default gateway URL will be https://provenance-gateway.datafund.io. Users can customize the URL using the --gateway-url flag or the BEE_GATEWAY_URL environment variable for local Bee nodes.

Phase 2: New Gateway Features

Once the dual backend support is in place, the second phase will introduce new features specific to the gateway. These features will enhance the CLI's functionality and leverage the capabilities of the provenance gateway. These new features will increase the value of the CLI and increase the usability. The new features will be:

  • stamps list command: Allows users to view a list of their stamps.
  • stamps extend command: Allows users to extend the validity of their stamps.
  • wallet command: Provides wallet management functionality.
  • health command: Checks the health status of the gateway.

Phase 3: Deprecate Local Backend (Optional)

The final phase considers the eventual deprecation of the local Bee node support, depending on the reliability and performance of the gateway. The goal is to create a more streamlined experience, with the gateway as the primary backend. This phase will be based on the experience and feedback from the first two phases. The options for this phase are:

  • Removing the local Bee support entirely if the gateway proves reliable. This will simplify the CLI and focus on a single, optimized backend.
  • Retaining local Bee support as a fallback option for offline or development use. This ensures that users have an alternative in cases where the gateway is unavailable.

Implementation Tasks: Breaking Down the Work

The implementation phase will involve several specific tasks, each addressing different aspects of the migration. These tasks have been broken down to facilitate a systematic approach and ensure that all aspects of the migration are addressed.

  • Modifying existing commands: Update existing commands to use the new gateway API endpoints.
  • Adding new commands: Implement the new features specific to the gateway, such as stamps list, stamps extend, and wallet.
  • Testing: Implement comprehensive testing to ensure that the migration does not introduce any regressions and that the new features work as expected.

Each task is supported by detailed linked issues to ensure that developers have a clear understanding of the scope and requirements of each task.

Testing Strategy: Ensuring a Seamless Transition

A robust testing strategy is essential to guarantee a smooth transition and ensure that the CLI functions correctly with the new gateway API. The testing strategy will include various types of tests, each designed to validate different aspects of the migration.

  • Mock Tests: These tests will simulate interactions with both the gateway and the local Bee node. Mock tests are designed to provide control and repeatability to the testing process.
  • Integration Tests: Integration tests will be conducted against the gateway, using test stamps to simulate real-world usage scenarios. These tests will use real API calls and provide a more comprehensive validation of the CLI's behavior.
  • Regression Tests: Existing tests will be maintained to ensure that the local backend mode continues to function correctly. This is important to ensure that the current functionalities of the CLI are maintained.

The goal is to provide comprehensive coverage and confidence in the migrated CLI.

Conclusion: A Future-Proof CLI

Migrating the CLI to use the provenance-gateway.datafund.io API represents a crucial step in modernizing the tool. This migration not only improves functionality but also positions the CLI for future growth and innovation within the swarm ecosystem. The phased approach, combined with a comprehensive testing strategy, ensures a seamless transition. The new features provided by the gateway, such as the stamps extend and wallet commands, offer enhanced capabilities for users. The migration will result in a more user-friendly and feature-rich CLI, which is essential for continued success and adoption. By migrating, the CLI can keep pace with evolving needs. With its enhanced features and improved reliability, the updated CLI will serve as a vital tool for interacting with the swarm network.

For further information on the Swarm network and related technologies, you may find the following resources useful: