Akita Phoenix and Akita Hexagon for Reticulum

Akita Reticulum Web Services

Organization: Akita Engineering (www.akitaengineering.com) License: GPLv3

This repository contains two Python applications providing web-like services over the Reticulum Network Stack:

• Akita Phoenix: A text-based web browser with discovery, RNS names, bookmarks, configurable caching, POST/PUT/DELETE support, and enhanced plugin hooks.
• Akita Hexagon: A lightweight web server with discovery announcement, configurable request limits, optional directory listing and gzip responses, plugin-based path handling (GET/POST/PUT/DELETE), lifecycle hooks, and HTML error pages.

Ideal for low-bandwidth, terminal-based, or specialized network environments.

Features

Akita Phoenix (Browser)

• Server Discovery & RNS: Connect via discovery, RNS name (e.g., myweb.serv), or destination hash.
• Bookmarks: Save (addbm), list (listbm), navigate (gobm) favorite sites. Stored in ~/.config/akita-phoenix/bookmarks.json.
• Configurable Caching: Time-based response caching in ~/.config/akita-phoenix/cache/. TTL configurable via ~/.config/akita-phoenix/config.json. Use r to refresh.
• Compressed Responses: Requests gzip-compressed responses when available and transparently decodes them.
• Text Rendering: Displays text/html, text/plain, and other common text types (application/json, text/css, etc.). Informs about binary types.
• Navigation: Follow relative links ([Num]), Back (b), Refresh (r), Home (h).
• HTTP Methods: Send GET (default), POST (post <path> <key=value&...>), PUT (put <path> <data>), DELETE (del <path>).
• Plugin System:
  • modify_request: Alter outgoing request (method, path, headers, body).
  • process_content: Modify raw response bytes before parsing.
  • post_parse_content: Modify extracted text/links after parsing.
  • modify_links: Filter or change the list of links before display.
  • Plugins loaded from src/akita_reticulum_web_services/plugins/phoenix/. Supports priorities and selective enabling.

Akita Hexagon (Server)

• Service Announcement: Announces akita_web/hexagon for discovery.
• Configurable: Settings via ~/.config/akita-hexagon/config.json (timeouts, size limits, directory listing, custom headers, optional gzip compression, plugin management) and command-line overrides.
• Interface Validation: Can require a named active Reticulum interface before startup. Interface enablement still comes from the underlying Reticulum configuration.
• Plugin System:
  • Path Handling: Plugins register URL paths (/myplugin/api) via register_path_handler in load(). Requests are routed to handle_registered_path (supports GET/POST/PUT/DELETE/etc.).
  • Lifecycle Hooks: server_startup(config, destination) and server_shutdown() for setup/cleanup (see startup_logger.py example).
  • Response Hook: modify_response allows altering default responses/errors.
  • Priority System: Plugins have priorities for execution order. Selective loading via config.
  • Plugins loaded from src/akita_reticulum_web_services/plugins/hexagon/. Includes echo_post.py and startup_logger.py examples.
• File Serving: Serves local files for GET requests if no plugin handles the path. Uses mimetypes. Optional directory listing and gzip compression for clients that accept it.
• Basic HTTP/1.0: Handles GET by default. Handles POST/PUT/DELETE/other methods via plugins. Requires Content-Length for body methods.
• Error Handling: Serves HTML error pages (from src/.../templates/) for common 4xx/5xx errors. Logs errors. Custom error templates.
• Multi-threaded Request Handling: Uses a handler thread per accepted link.

Installation

1. Prerequisites: Python 3.7+, running/configured Reticulum instance.
2. Clone: git clone <repo_url> && cd Akita-Reticulum-Web-Services
3. Install deps: pip install -r requirements.txt

Documentation

• Configuration Reference: Key-by-key browser and server configuration details, defaults, caveats, and example JSON.
• Development Notes: Local virtual environment workflow, linting/compile commands, and project style settings.
• Use Cases: Practical deployment and workflow ideas for combining Akita Hexagon and Akita Phoenix.

Configuration

• Server (~/.config/akita-hexagon/config.json): Controls serve directory, required active interface name, identity path, log level, timeouts (request/link), size limits (header/POST body), gzip compression, custom headers, enabled plugins list, and directory listing. See docs/configuration.md for defaults and caveats.
• Browser (~/.config/akita-phoenix/config.json): Controls cache TTL, timeouts (request/link/RNS resolve), enabled plugins, user agent, and GET redirect behavior. See docs/configuration.md for defaults and examples.

(Create these JSON files if you want to override defaults)

Usage

1. Running the Akita Hexagon Server

• Start: python3 scripts/run_hexagon_server.py
• Config file override: python3 scripts/run_hexagon_server.py -c /path/to/config.json
• Serve directory override: python3 scripts/run_hexagon_server.py --serve-dir ./examples
• Log level override: python3 scripts/run_hexagon_server.py --log-level DEBUG
• Required interface: python3 scripts/run_hexagon_server.py -i <iface> (<iface> must already be an active Reticulum interface name)

2. Running the Akita Phoenix Browser

• Discover: python3 scripts/run_phoenix_browser.py
• Connect (Name/Hash): python3 scripts/run_phoenix_browser.py <target>
• Specify Path: Add -p /path/page.html
• Alternate config file: Add --config /path/to/config.json
• Verbose logging: Add --debug or --log-level DEBUG

The browser fetches the initial path immediately after startup and follows GET redirects when follow_redirects is enabled in browser config.

• Browser Commands:
  • [Num]: Follow link.
  • b: Back.
  • r: Refresh.
  • h: Home (/).
  • p <path> <data>: Send POST (e.g., p /echo name=test&val=123).
  • put <path> <data>: Send PUT.
  • del <path>: Send DELETE.
  • a [name]: Add bookmark.
  • l: List bookmarks.
  • g <num>: Go to bookmark.
  • q: Quit.

Plugins

• Browser: Place in src/.../plugins/phoenix/. Inherit PhoenixPluginBase. Set self.priority for execution order. See base class docstrings for hooks. Enable/disable via config.
• Server: Place in src/.../plugins/hexagon/. Inherit HexagonPluginBase. Set self.priority for execution order. Use load() to register paths via self.register_path_handler(...). Implement handle_registered_path(...) (return True if handled). Use lifecycle hooks server_startup/server_shutdown. Enable/disable via config.

Notes

• Reticulum Setup: Essential.
• POST: Browser sends URL-encoded. Server relies on plugins registering paths.
• Config caveat: max_concurrent_connections still exists in server defaults for compatibility, but the current request loop does not enforce a connection cap.
• Security: Basic. Use cautiously.

License

GPLv3 - see LICENSE file.