Kaede Protocol Manager v0.2.0

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.
• .kprotocol File Creation: NEW: You can now create .kprotocol files directly from a protocol directory using the make protocol command, simplifying the protocol packaging process.
• 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.

make protocol (NEW)

Creates a .kprotocol file from a directory containing protocol definition files. This command simplifies the process of packaging a custom protocol for installation.

Usage:

kaede-protocol-manager make protocol <protocol_directory_path> [--output <output_file_name>]

Options:

• protocol: Specifies that you are making a protocol .kprotocol file (currently the only supported resource type).
• <protocol_directory_path>: (Required) The path to the directory containing your protocol definition files. This directory should contain a subdirectory named protocol with data.json, request_parser.py, and response_formatter.py inside.
• --output <output_file_name>: (Optional) Specify a custom name for the output .kprotocol file. If not provided, the file name will be automatically generated based on the protocol name defined in data.json. Ensure the output file name ends with .kprotocol or it will be added automatically.

Example:

kaede-protocol-manager make protocol my_protocol_source

This command will create a .kprotocol file (e.g., source-test-proto.kprotocol if your protocol name in data.json is source-test-proto) in the my_protocol_source directory, packaging the protocol definition from the my_protocol_source/protocol subdirectory.

kaede-protocol-manager make protocol my_protocol_source --output custom_protocol.kprotocol

This command will create a .kprotocol file named custom_protocol.kprotocol in the my_protocol_source directory.

Creating a .kprotocol File (Manual Method - Now Optional with make protocol command)

While the make protocol command simplifies .kprotocol creation, you can still create .kprotocol files manually if needed. A .kprotocol file is a .zip archive that bundles all the necessary components of a custom API protocol.

Structure of a .kprotocol Archive:

A .kprotocol archive must contain the following files within a subdirectory named protocol at the root level:

<protocol_name>.kprotocol (ZIP Archive)
│
└── protocol/
│   └── 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:

• protocol/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).

• protocol/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
  

• protocol/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 Manually Create a .kprotocol File:

1. Create a directory structure like this: my_protocol_source/protocol/.
2. Inside my_protocol_source/protocol/, 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 protocol directory into a .zip archive. Make sure the protocol directory itself is at the root of the zip, and inside it are the three files.
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 - cleaverdeath@gmail.com

GitHub Repository