kaede-protocol-manager 0.1.0

CLI tool to manage custom API protocols for Kaede API Creation package.

Kaede Protocol Manager

A CLI tool to manage custom API protocols for the Kaede API Creation package.

The Kaede Protocol Manager (kaede-protocol-manager) is a command-line interface (CLI) utility designed to streamline the installation and management of custom API protocols. It works in conjunction with the Kaede API Creation package (kaede-api-creation) by providing a standardized way to package, install, and verify custom protocol definitions.

Features

• Compressed Protocol Installation: Installs custom API protocols from a single, compressed .kprotocol file (.zip archive).
• Protocol Initialization: Offers a command to initialize and perform basic validation of an installed protocol, ensuring it is correctly set up.
• Bundled Protocol Definitions: Protocols are packaged as .kprotocol files, which are .zip archives containing all necessary definition files (data.json, request_parser.py, response_formatter.py).
• Structured Data Storage (data.json): Protocol metadata, headers, and status codes are stored in a structured data.json file within the .kprotocol archive.
• Python Logic Encapsulation: Protocol-specific request parsing and response formatting logic are contained within request_parser.py and response_formatter.py files within the .kprotocol archive.
• Simple CLI Interface: Provides an intuitive command-line interface for managing protocols.

Installation

To install kaede-protocol-manager, navigate to the directory containing the setup.py file and execute the following command using pip:

pip install .

This command will install the kaede-protocol-manager package and make the kaede-protocol-manager command available in your system's command-line environment.

Usage

The kaede-protocol-manager CLI provides the following commands for managing custom API protocols:

install protocol

Installs a new API protocol from a .kprotocol file.

Usage:

kaede-protocol-manager install protocol --file <protocol_file_path> --name <protocol_name>

Options:

• protocol: Specifies that you are installing a protocol (currently the only supported resource type).
• --file <protocol_file_path>: (Required) The path to the .kprotocol file (which is a .zip archive) containing the protocol definition.
• --name <protocol_name>: (Required) The name you wish to assign to this protocol. This name will be used to reference the protocol when creating APIs with kaede-api-creation.

Example:

kaede-protocol-manager install protocol --file my_custom_protocol.kprotocol --name my-protocol

This command will install the protocol defined in my_custom_protocol.kprotocol and name it my-protocol. The protocol definition will be extracted to the ~/.kaede_protocols/my-protocol directory.

initialize protocol

Initializes and validates an installed protocol. This command performs basic checks to ensure that the protocol directory exists and that essential files (data.json, request_parser.py, response_formatter.py) are present after installation.

Usage:

kaede-protocol-manager initialize protocol --name <protocol_name>

Options:

• protocol: Specifies that you are initializing a protocol (currently the only supported resource type).
• --name <protocol_name>: (Required) The name of the protocol to initialize.

Example:

kaede-protocol-manager initialize protocol --name my-protocol

This command will initialize the protocol named my-protocol, verifying the presence of the protocol directory and required definition files.

Creating a .kprotocol File

A .kprotocol file is a .zip archive that bundles all the necessary components of a custom API protocol. To create a .kprotocol file, you need to organize your protocol definition files into a specific directory structure and then compress them into a .zip archive, renaming the archive to have a .kprotocol extension.

Structure of a .kprotocol Archive:

A .kprotocol archive must contain the following files at the root level:

<protocol_name>.kprotocol (ZIP Archive)
│
└── data.json
│   └── Contains protocol metadata, headers, and status codes in JSON format.
│
└── request_parser.py
│   └── Python file defining the `parse_kaede_request` function.
│
└── response_formatter.py
    └── Python file defining the `format_kaede_response` function.

File Descriptions within the .kprotocol Archive:

• data.json: This file is a JSON document that defines the structured data for your protocol. It should contain the following top-level keys (all are required):

  {
    "PROTOCOL": {
      "name": "<protocol_name>",        // (Required) - Name of the protocol (must match installation name in most cases)
      "version": "<protocol_version>",    // (Required) - Version of the protocol (e.g., "1.0", "v2")
      "description": "<protocol_description>" // (Optional) - Human-readable description
    },
    "HEADERS": {                      // (Optional) - Default headers for responses
      "<header_name_1>": "<header_value_1>",
      "<header_name_2>": "<header_value_2>",
      // ... more headers ...
    },
    "STATUS_CODES": {                 // (Optional) - Custom status codes
      "<status_code_number_1>": "<status_code_name_1>", // Status code number (string) and name
      "<status_code_number_2>": "<status_code_name_2>",
      // ... more status codes ...
    }
  }
  

  • PROTOCOL Block:

    • name: The name of the protocol (string). It is recommended to keep this consistent with the --name used during installation.
    • version: The protocol version (string or number).
    • description (Optional): A human-readable description of the protocol.

  • HEADERS Block (Optional): Defines default headers (key-value pairs) that will be included in responses when using this protocol.

  • STATUS_CODES Block (Optional): Defines custom status codes (key-value pairs where keys are status code numbers as strings, and values are status code names).

• request_parser.py: This Python file must define a function named parse_kaede_request. This function is responsible for parsing raw request data (received by the server) and converting it into a Request object that can be understood by your API handlers.

  # Example content of request_parser.py
  class MyProtocolRequest: # Custom Request class (optional, but recommended)
      def __init__(self, method, path, headers, body):
          self.method = method
          self.path = path
          self.headers = headers
          self.body = body
  
  def parse_kaede_request(raw_request_data):
      """Parses raw request data and returns a Request object."""
      # ... (Your protocol's parsing logic here) ...
      request = MyProtocolRequest(method="GET", path="/", headers={}, body="") # Example
      return request
  

• response_formatter.py: This Python file must define a function named format_kaede_response. This function takes a Response object (returned by your API handlers) and formats it into bytes that can be sent back as a response over the network.

  # Example content of response_formatter.py
  def format_kaede_response(response):
      """Formats a Response object into bytes for sending."""
      # ... (Your protocol's formatting logic here) ...
      response_bytes = b"Example Response Data" # Example
      return response_bytes
  

Steps to Create a .kprotocol File:

1. Create a directory (e.g., my_protocol_source/).
2. Inside this directory, create:
   • data.json (with your protocol's metadata, headers, status codes).
   • request_parser.py (with your parse_kaede_request function).
   • response_formatter.py (with your format_kaede_response function).
3. Compress the contents of my_protocol_source/ into a .zip archive. Do not zip the directory itself, but the files inside it.
4. Rename the created .zip archive to have a .kprotocol extension (e.g., my_protocol.kprotocol).

You can then use this .kprotocol file to install your custom protocol using the kaede-protocol-manager install protocol command.

For Developers

Contributions to kaede-protocol-manager are welcome! Please refer to the project's repository on GitHub for contribution guidelines, issue tracking, and to submit pull requests.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Author

Kaede Dev Kento Hinode - [e-mail]

GitHub Repository