Nauyaca

https://nauyaca.readthedocs.io/en/latest
Admin
Nauyaca is a modern, high-performance Python implementation of the Gemini protocol providing both...
Tokens:116,578
Snippets:574
Trust Score:8.3
Update:10 months ago
Show doc for...
Tokens:
Raw
### Install Nauyaca from Source

Source: https://nauyaca.readthedocs.io/en/latest/quickstart

Installs Nauyaca by cloning the repository and synchronizing dependencies using uv. This method is suitable for development or contributing to Nauyaca.

```shell
git clone https://github.com/alanbato/nauyaca.git
cd nauyaca
uv sync

```

--------------------------------

### Create Basic Gemini Server Example

Source: https://nauyaca.readthedocs.io/en/latest/quickstart

Provides an example of how to set up and run a basic Gemini server using Nauyaca. It configures the server's host, port, and document root, and automatically generates a certificate for TLS. The server runs until interrupted.

```python
import asyncio
from pathlib import Path
from nauyaca.server.config import ServerConfig
from nauyaca.server.server import start_server

async def main():
    # Configure server
    config = ServerConfig(
        host="localhost",
        port=1965,
        document_root=Path("./my-capsule"),
        # Optional: specify certificate files
        # certfile=Path("./certs/cert.pem"),
        # keyfile=Path("./certs/key.pem"),
    )

    # Start server (runs until interrupted)
    print(f"Starting server on {config.host}:{config.port}")
    print(f"Serving files from: {config.document_root}")
    print("Press Ctrl+C to stop")

    await start_server(config)

if __name__ == "__main__":
    asyncio.run(main())

```

--------------------------------

### Install Nauyaca CLI Tool

Source: https://nauyaca.readthedocs.io/en/latest/quickstart

Installs Nauyaca as a standalone command-line tool using uv. This is the recommended method for running Nauyaca as a CLI utility.

```shell
uv tool install nauyaca

```

--------------------------------

### Install uv Package Manager

Source: https://nauyaca.readthedocs.io/en/latest/quickstart

Installs the uv package manager, which is recommended for managing Python dependencies and Nauyaca. This command fetches and executes an installation script.

```shell
curl -LsSf https://astral.sh/uv/install.sh | sh

```

--------------------------------

### Fetch Gemini Content with Simple Client Example

Source: https://nauyaca.readthedocs.io/en/latest/quickstart

Demonstrates how to fetch and process content from a Gemini URL using the GeminiClient. It includes basic error handling for success, redirects, and other errors. The client uses TOFU (Trust On First Use) validation by default.

```python
import asyncio
from nauyaca.client import GeminiClient

async def main():
    # Create client with TOFU validation (recommended)
    async with GeminiClient() as client:
        response = await client.get("gemini://geminiprotocol.net/")

        # Check response status
        if response.is_success():
            print(f"Content-Type: {response.meta}")
            print(f"Body length: {len(response.body)} bytes")
            print("\nContent:")
            print(response.body)
        elif response.is_redirect():
            print(f"Redirected to: {response.meta}")
        else:
            print(f"Error {response.status}: {response.meta}")

if __name__ == "__main__":
    asyncio.run(main())

```

--------------------------------

### Python Gemini Server Example

Source: https://nauyaca.readthedocs.io/en/latest/index

Shows how to set up and start a basic Nauyaca Gemini server. It configures the server with a host, port, and document root, then starts the server to listen for incoming connections.

```python
import asyncio
from nauyaca.server import GeminiServer
from nauyaca.server.config import ServerConfig

async def main():
    config = ServerConfig(
        host="localhost",
        port=1965,
        document_root="./capsule"
    )

    server = GeminiServer(config)
    await server.start()

asyncio.run(main())
```

--------------------------------

### Development Setup: Verify Test Suite

Source: https://nauyaca.readthedocs.io/en/latest/installation

Command to run the Nauyaca test suite using 'uv run pytest'. Ensures that the development setup is correct and all tests pass.

```shell
uv run pytest
```

--------------------------------

### Install Nauyaca from Source

Source: https://nauyaca.readthedocs.io/en/latest/installation

Steps to install Nauyaca from its source code repository for development purposes. This method installs the latest unreleased features and requires Git. It uses 'uv sync' to install dependencies.

```shell
# Clone the repository
git clone https://github.com/alanbato/nauyaca.git
cd nauyaca

# Install with development dependencies
uv sync
```

--------------------------------

### Minimal Server Setup

Source: https://nauyaca.readthedocs.io/en/latest/reference/api/server

This snippet demonstrates how to start a basic Gemini server with default settings using the Server API.

```APIDOC
## Minimal Server Setup

### Description
Start a basic Gemini server with default settings.

### Method
N/A (Programmatic setup)

### Endpoint
N/A (Programmatic setup)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import asyncio
from pathlib import Path
from nauyaca.server.config import ServerConfig
from nauyaca.server.server import start_server

async def main():
    config = ServerConfig(
        host="localhost",
        port=1965,
        document_root=Path("./capsule"),
        certfile=Path("cert.pem"),
        keyfile=Path("key.pem")
    )

    await start_server(config)

if __name__ == "__main__":
    asyncio.run(main())
```

### Response
#### Success Response (200)
N/A (Server starts and runs)

#### Response Example
N/A
```

--------------------------------

### Development Setup: Code Quality Checks

Source: https://nauyaca.readthedocs.io/en/latest/installation

Commands to perform code quality checks for Nauyaca development using 'uv run'. Includes linting with Ruff, type checking with Mypy, and tests with coverage reporting.

```shell
# Run linting
uv run ruff check src/ tests/

# Run type checking
uv run mypy src/

# Run tests with coverage
uv run pytest --cov=src/nauyaca --cov-report=html
```

--------------------------------

### Install Nauyaca as CLI Tool

Source: https://nauyaca.readthedocs.io/en/latest/installation

Installs Nauyaca as a command-line interface tool using 'uv' or 'pipx'. This makes the 'nauyaca' command globally available for running servers and clients.

```shell
uv tool install nauyaca
```

```shell
pipx install nauyaca
```

--------------------------------

### Minimal Server Setup in Python

Source: https://nauyaca.readthedocs.io/en/latest/reference/api/server

This code snippet demonstrates how to start a basic Gemini server using default settings. It requires the asyncio, pathlib, ServerConfig, and start_server modules. The function configures the host, port, document root, certificate file, and key file before starting the server.

```python
import asyncio
from pathlib import Path
from nauyaca.server.config import ServerConfig
from nauyaca.server.server import start_server

async def main():
    config = ServerConfig(
        host="localhost",
        port=1965,
        document_root=Path("./capsule"),
        certfile=Path("cert.pem"),
        keyfile=Path("key.pem")
    )

    await start_server(config)

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Server Setup with Configuration File

Source: https://nauyaca.readthedocs.io/en/latest/reference/api/server

This snippet shows how to load server configuration from a TOML file and start the server with additional options.

```APIDOC
## Server Setup with Configuration File

### Description
Load server configuration from a TOML file and start the server with specified options.

### Method
N/A (Programmatic setup)

### Endpoint
N/A (Programmatic setup)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import asyncio
from pathlib import Path
from nauyaca.server.config import ServerConfig
from nauyaca.server.server import start_server

async def main():
    # Load from TOML
    config = ServerConfig.from_toml(Path("config.toml"))

    # Start server with configuration
    await start_server(
        config,
        enable_directory_listing=True,
        log_level="INFO"
    )

if __name__ == "__main__":
    asyncio.run(main())
```

### Response
#### Success Response (200)
N/A (Server starts and runs)

#### Response Example
N/A
```

--------------------------------

### Fetch Local Gemini Page

Source: https://nauyaca.readthedocs.io/en/latest/quickstart

Fetches content from the locally served Gemini capsule using the nauyaca get command. This tests if the server is running and serving content correctly.

```shell
nauyaca get gemini://localhost/

```

--------------------------------

### Development Setup: Pre-commit Hooks

Source: https://nauyaca.readthedocs.io/en/latest/installation

Command to install pre-commit hooks for Nauyaca development. These hooks automatically run checks before each commit, ensuring code quality.

```shell
uv run pre-commit install
```

--------------------------------

### Test Nauyaca Client

Source: https://nauyaca.readthedocs.io/en/latest/installation

Command to test the Nauyaca client by fetching a resource from a public Gemini server. Prompts for Trust On First Use (TOFU) for certificates on the first connection.

```shell
nauyaca get gemini://geminiprotocol.net/
```

--------------------------------

### Nauyaca CLI Commands

Source: https://nauyaca.readthedocs.io/en/latest/index

Provides examples of common Nauyaca commands for managing a Gemini server and client. Includes starting a server, fetching resources, and managing trusted certificates using TOFU.

```bash
# Start a server
nauyaca serve ./capsule --host localhost --port 1965

# Fetch a resource
nauyaca get gemini://geminiprotocol.net/

# Manage trusted certificates
nauyaca tofu list
nauyaca tofu trust example.com
```

--------------------------------

### Serve Local Gemini Capsule

Source: https://nauyaca.readthedocs.io/en/latest/quickstart

Starts the Nauyaca server to host Gemini content from a specified directory. It automatically generates a self-signed certificate for local development.

```shell
nauyaca serve ./my-capsule

```

--------------------------------

### Verify Nauyaca CLI Installation

Source: https://nauyaca.readthedocs.io/en/latest/installation

Command to verify the Nauyaca CLI tool installation by displaying the help text. This confirms the command is accessible and functional.

```shell
nauyaca --help
```

--------------------------------

### Manage Trusted Certificates (TOFU)

Source: https://nauyaca.readthedocs.io/en/latest/quickstart

Manages Trust-On-First-Use (TOFU) certificates for Gemini hosts. Commands include listing, trusting, revoking, exporting, and importing certificates.

```shell
# List all known hosts
auyaca tofu list

# Manually trust a host
auyaca tofu trust example.com

# Revoke trust (force re-trust on next connection)
auyaca tofu revoke old-server.com

# Export TOFU database for backup
auyaca tofu export ~/tofu-backup.toml

# Import TOFU database
auyaca tofu import ~/tofu-backup.toml

```

--------------------------------

### Add Nauyaca to Python Project

Source: https://nauyaca.readthedocs.io/en/latest/quickstart

Adds Nauyaca as a library dependency to an existing Python project using uv. Alternatively, it shows how to initialize a new project and add Nauyaca.

```shell
# Add to existing project
uv add nauyaca

# Or start a new project
uv init my-gemini-project
cd my-gemini-project
uv add nauyaca

```

--------------------------------

### Starting Nauyaca Server with CLI Overrides

Source: https://nauyaca.readthedocs.io/en/latest/how-to/configure-server

Example command demonstrating how CLI arguments (host and port) override the settings defined in a TOML configuration file.

```Shell
# Starts on 0.0.0.0:8080 (CLI overrides config file)
nauyaca serve --config config.toml --host 0.0.0.0 --port 8080


```

--------------------------------

### Install and Configure Promtail for Loki

Source: https://nauyaca.readthedocs.io/en/latest/how-to/logging

This code demonstrates the process of setting up Promtail to ship Nauyaca logs to Loki. It includes downloading Promtail, unzipping it, and providing a sample `promtail-config.yml` file that configures Promtail to scrape and forward JSON logs from Nauyaca to a local Loki instance.

```bash
# Download and configure Promtail
wget https://github.com/grafana/loki/releases/download/v2.9.0/promtail-linux-amd64.zip
unzip promtail-linux-amd64.zip

```

```yaml
server:
  http_listen_port: 9080
  grpc_listen_port: 0

positions:
  filename: /tmp/positions.yaml

clients:
  - url: http://localhost:3100/loki/api/v1/push

scrape_configs:
  - job_name: nauyaca
    static_configs:
      - targets:
          - localhost
        labels:
          job: nauyaca
          __path__: /var/log/nauyaca/*.log
    pipeline_stages:
      - json:
          expressions:
            level: level
            event: event
            client_ip_hash: client_ip_hash
            status: status
      - labels:
          level:
          event:

```

```bash
./promtail-linux-amd64 -config.file=promtail-config.yml

```

--------------------------------

### Create Gemini Capsule Content

Source: https://nauyaca.readthedocs.io/en/latest/quickstart

Creates a directory and a sample Gemini text file (index.gmi) to serve as a local Gemini capsule. This demonstrates the basic structure of Gemini content.

```shell
mkdir my-capsule
cat > my-capsule/index.gmi << 'EOF'
# Welcome to My Gemini Capsule!

This is my first Gemini page.

## What is Gemini?

Gemini is a modern, privacy-focused protocol that sits between Gopher and the web.

=> gemini://geminiprotocol.net/ Learn more about Gemini

## Links

=> about.gmi About me
=> /blog Blog posts

Thanks for visiting!
EOF

```

--------------------------------

### Programmatic TOFU Usage (Python)

Source: https://nauyaca.readthedocs.io/en/latest/how-to/setup-tofu

Provides an example of programmatic TOFU usage in Python using the `GeminiClient`. It demonstrates handling `CertificateChangedError` when a host's certificate changes.

```python
import asyncio
from nauyaca.client.session import GeminiClient
from nauyaca.security.tofu import CertificateChangedError

async def main():
    try:
        async with GeminiClient(trust_on_first_use=True) as client:
            response = await client.get("gemini://example.com/")
            print(response.body)
    except CertificateChangedError as e:
        print(f"Certificate changed for {e.hostname}")
        print(f"Old: {e.old_fingerprint}")
        print(f"New: {e.new_fingerprint}")
        # Handle appropriately

asyncio.run(main())
```

--------------------------------

### Fetch Public Gemini Page

Source: https://nauyaca.readthedocs.io/en/latest/quickstart

Fetches content from a remote Gemini server, specifically the official Gemini protocol homepage. This demonstrates Nauyaca's ability to browse the Gemini web.

```shell
nauyaca get gemini://geminiprotocol.net/

```

--------------------------------

### Handle Gemini Responses and Errors with Advanced Client

Source: https://nauyaca.readthedocs.io/en/latest/quickstart

Illustrates advanced client usage for handling various Gemini response types and errors, including redirects, input requests, temporary/permanent failures, and certificate-related issues. It uses a `GeminiClient` with configurable timeouts and redirect limits.

```python
import asyncio
from nauyaca.client import GeminiClient
from nauyaca.security.tofu import CertificateChangedError

async def fetch_with_error_handling(url: str):
    try:
        async with GeminiClient(timeout=30, max_redirects=5) as client:
            response = await client.get(url)

            # Success (2x status codes)
            if response.is_success():
                return response.body

            # Redirect (3x status codes)
            elif response.is_redirect():
                print(f"Redirected to: {response.meta}")
                return await fetch_with_error_handling(response.meta)

            # Input required (1x status codes)
            elif 10 <= response.status < 20:
                print(f"Input requested: {response.meta}")
                user_input = input("Enter input: ")
                # Re-request with query parameter
                return await fetch_with_error_handling(f"{url}?{user_input}")

            # Temporary failure (4x status codes)
            elif 40 <= response.status < 50:
                print(f"Temporary error: {response.meta}")
                return None

            # Permanent failure (5x status codes)
            elif 50 <= response.status < 60:
                print(f"Permanent error: {response.meta}")
                return None

            # Certificate required (6x status codes)
            elif 60 <= response.status < 70:
                print(f"Client certificate required: {response.meta}")
                return None

    except CertificateChangedError as e:
        print(f"Certificate changed for {e.hostname}:{e.port}")
        print(f"Old: {e.old_fingerprint}")
        print(f"New: {e.new_fingerprint}")
        return None
    except TimeoutError:
        print(f"Request timed out")
        return None
    except ConnectionError as e:
        print(f"Connection failed: {e}")
        return None

# Use the function
asyncio.run(fetch_with_error_handling("gemini://geminiprotocol.net/"))

```

--------------------------------

### View Gemini Response Details

Source: https://nauyaca.readthedocs.io/en/latest/quickstart

Fetches Gemini content and displays detailed response information, including status, meta, and URL, using the --verbose flag. This is useful for debugging and understanding server responses.

```shell
nauyaca get --verbose gemini://geminiprotocol.net/

```

--------------------------------

### TOFU Database Exported TOML Structure

Source: https://nauyaca.readthedocs.io/en/latest/how-to/setup-tofu

Example structure of the TOML file generated by `nauyaca tofu export`. It includes metadata and host entries with their certificate details, first seen, and last seen timestamps.

```toml
[_metadata]
exported_at = "2025-11-29T12:00:00+00:00"
version = "1.0"

[hosts."example.com:1965"]
hostname = "example.com"
port = 1965
fingerprint = "sha256:abc123..."
first_seen = "2025-01-15T10:30:00+00:00"
last_seen = "2025-11-29T11:45:00+00:00"

```

--------------------------------

### Example Usage of start_server (Python)

Source: https://nauyaca.readthedocs.io/en/latest/reference/api/server

Demonstrates how to use the 'start_server' function to launch a Gemini server. It shows the creation of a 'ServerConfig' object with essential parameters like host, port, document root, and TLS certificates, and then initiates the server using asyncio.run().

```python
import asyncio
from pathlib import Path

# Assuming ServerConfig is defined elsewhere and imported
# from nauyaca.config import ServerConfig 

config = ServerConfig(
    host="localhost",
    port=1965,
    document_root=Path("./capsule"),
    certfile=Path("cert.pem"),
    keyfile=Path("key.pem")
)

asyncio.run(start_server(config))

```

--------------------------------

### Configure and Start Nauyaca Server

Source: https://nauyaca.readthedocs.io/en/latest/reference/api/server

This Python snippet demonstrates how to initialize `ServerConfig` with host, port, document root, and certificate paths, then asynchronously start the server using `asyncio.run` and a `start_server` function. It also includes logic for resolving configuration values, setting up logging, validating the configuration, and creating a router with a static file handler.

```python
>>> config = ServerConfig(
...     host="localhost",
...     port=1965,
...     document_root=Path("./capsule"),
...     certfile=Path("cert.pem"),
...     keyfile=Path("key.pem")
... )
>>> asyncio.run(start_server(config))

# Resolve hash_ips from config if not explicitly set
effective_hash_ips = hash_ips if hash_ips is not None else config.hash_client_ips

# Configure logging first
configure_logging(
    log_level=log_level,
    log_file=log_file,
    json_logs=json_logs,
    hash_ips=effective_hash_ips,
)
logger = get_logger(__name__)

# Validate configuration
config.validate()

# Resolve max_file_size from config if not explicitly set
effective_max_file_size = (
    max_file_size if max_file_size is not None else config.max_file_size
)

# Create router and static file handler
router = Router()
static_handler = StaticFileHandler(
    config.document_root,
    enable_directory_listing=enable_directory_listing,
    max_file_size=effective_max_file_size,
)

# Set up default 404 handler
def default_404_handler(request: object) -> GeminiResponse:
    from ..protocol.request import GeminiRequest

    if isinstance(request, GeminiRequest):
        path = request.path
    else:
        path = "/"
    return GeminiResponse(
        status=StatusCode.NOT_FOUND.value,
        meta="text/gemini",
        body=error_404(path),
    )

router.set_default_handler(default_404_handler)

# Add route for all paths - static file handler
# This catches everything not explicitly routed
from .router import RouteType

router.add_route("/", static_handler.handle, route_type=RouteType.PREFIX)

# Determine if we need to request client certificates
# (needed for CertificateAuth middleware to work)
# PyOpenSSL is used if ANY path rule requires certificates
request_client_cert = certificate_auth_config is not None and any(
    rule.require_cert or rule.allowed_fingerprints is not None
    for rule in certificate_auth_config.path_rules
)

# Determine if we need PyOpenSSL for client certificate support
# PyOpenSSL is required because Python's ssl module with OpenSSL 3.x
# silently rejects self-signed client certificates
use_pyopenssl = request_client_cert

# Create SSL context (only used when NOT using PyOpenSSL)
ssl_context: ssl.SSLContext | None = None
pyopenssl_ctx = None

if use_pyopenssl:
    # Use PyOpenSSL for proper self-signed client cert support
    if config.certfile and config.keyfile:
        pyopenssl_ctx = create_pyopenssl_server_context(
            str(config.certfile),
            str(config.keyfile),
            request_client_cert=True,
        )
        logger.info(
            "tls_configured",
            certfile=str(config.certfile),
            keyfile=str(config.keyfile),
            request_client_cert=True,
            tls_backend="pyopenssl",
        )
    else:
        # For testing: create self-signed certificate with PyOpenSSL
        pyopenssl_ctx = _create_self_signed_pyopenssl_context()
        logger.warning(
            "using_self_signed_certificate",
            mode="testing_only",
            tls_backend="pyopenssl",
        )
else:
    # Standard ssl module is fine when not requesting client certs
    if config.certfile and config.keyfile:
        ssl_context = create_server_context(
            str(config.certfile),
            str(config.keyfile),
            request_client_cert=False,
        )
        logger.info(
            "tls_configured",
            certfile=str(config.certfile),
            keyfile=str(config.keyfile),
            request_client_cert=False,
            tls_backend="stdlib",
        )
    else:
        # For testing: create self-signed certificate
        ssl_context = _create_self_signed_context(request_client_cert=False)
        logger.warning(
            "using_self_signed_certificate",
            mode="testing_only",
            tls_backend="stdlib",
        )

# Set up middleware chain
middlewares: list[Any] = []

# Add certificate auth if configured (check this first - before IP-based checks)
if certificate_auth_config:
    cert_auth = CertificateAuth(certificate_auth_config)
    middlewares.append(cert_auth)
    logger.info(
        "certificate_auth_enabled",
        path_rules_count=len(certificate_auth_config.path_rules),
        paths_requiring_cert=[
            rule.prefix
            for rule in certificate_auth_config.path_rules
            if rule.require_cert or rule.allowed_fingerprints is not None
        ],
    )

```

--------------------------------

### Check and Install Nauyaca Package

Source: https://nauyaca.readthedocs.io/en/latest/installation

Verifies if the 'nauyaca' package is installed in the current Python environment using 'pip list'. If it's not found, it provides commands to install it using either 'uv add' or 'pip install'.

```shell
# Check if nauyaca is installed
pip list | grep nauyaca

# If not found, install it
uv add nauyaca  # or: pip install nauyaca

```

--------------------------------

### Manage TOFU Database in Python

Source: https://nauyaca.readthedocs.io/en/latest/tutorials/building-a-client

Demonstrates how to interact with the Trust On First Use (TOFU) database using the `TOFUDatabase` class. This includes opening the database (using the default path if none is specified) and listing all hosts currently stored in the database along with their fingerprints.

```python
from pathlib import Path
from nauyaca.security.tofu import TOFUDatabase

# Open the database
tofu = TOFUDatabase()  # Uses default path ~/.nauyaca/tofu.db

# List all known hosts
hosts = tofu.list_hosts()
for host in hosts:
    print(f"{host['hostname']}:{host['port']} - {host['fingerprint']}")

```

--------------------------------

### Install uv Package Manager

Source: https://nauyaca.readthedocs.io/en/latest/installation

Commands to install the 'uv' package manager, recommended for faster Python package installations. Supports Linux/macOS via curl, Windows via PowerShell, and can also be installed using pip.

```shell
curl -LsSf https://astral.sh/uv/install.sh | sh
```

```powershell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```

```shell
pip install uv
```

--------------------------------

### ServerConfig Initialization Example (Python)

Source: https://nauyaca.readthedocs.io/en/latest/reference/api/server

An example of how to instantiate the ServerConfig dataclass in Python. This shows how to set the host, port, document root, and paths for certificate and key files when creating a server configuration object.

```python
config = ServerConfig(
    host="localhost",
    port=1965,
    document_root=Path("/var/gemini/capsule"),
    certfile=Path("/etc/gemini/cert.pem"),
    keyfile=Path("/etc/gemini/key.pem")
)

```

--------------------------------

### Check Python Version

Source: https://nauyaca.readthedocs.io/en/latest/installation

Command to verify the installed Python version. Requires Python 3.10 or higher.

```shell
python --version
```

--------------------------------

### Verify Nauyaca Version

Source: https://nauyaca.readthedocs.io/en/latest/installation

Command to check the installed Nauyaca version. Expected output is 'Nauyaca version 0.2.0'.

```shell
nauyaca version
```

--------------------------------

### Install Nauyaca as Python Library

Source: https://nauyaca.readthedocs.io/en/latest/installation

Instructions to install Nauyaca as a library for use in Python projects. Supports 'uv' for new or existing projects, and 'pip' within a virtual environment (recommended) or system-wide (not recommended).

```shell
# Create a new project
uv init my-gemini-project
cd my-gemini-project

# Add nauyaca as a dependency
uv add nauyaca
```

```shell
# Add to your existing project
uv add nauyaca
```

```shell
# In a virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install nauyaca
```

```shell
# Or install system-wide (not recommended)
pip install nauyaca
```

--------------------------------

### Basic GeminiClient Usage Example

Source: https://nauyaca.readthedocs.io/en/latest/reference/api/client

Demonstrates basic usage of the GeminiClient to fetch resources. This example utilizes an asynchronous context manager to ensure proper client initialization and cleanup. It requires an 'async' environment to run.

```python
>>> # Basic usage
>>> async with GeminiClient() as client:
...     response = await client.get('gemini://example.com/')
...     print(response.body)
```

--------------------------------

### Remove Nauyaca Source Directory

Source: https://nauyaca.readthedocs.io/en/latest/installation

Deletes the cloned repository directory for Nauyaca. This is the method for uninstalling if Nauyaca was installed directly from source code.

```shell
rm -rf nauyaca

```

--------------------------------

### Uninstall Nauyaca using pip

Source: https://nauyaca.readthedocs.io/en/latest/installation

Uninstalls the Nauyaca package using the 'pip uninstall' command. This is the standard procedure for removing the package when installed via pip.

```shell
pip uninstall nauyaca

```

--------------------------------

### Configure PATH for Nauyaca Installation (Windows)

Source: https://nauyaca.readthedocs.io/en/latest/installation

Adds the user's local bin directory to the PATH environment variable on Windows systems. This allows the system to find and execute commands installed in that location, including the 'nauyaca' command.

```batch
Add %USERPROFILE%\AppData\Local\bin to your PATH environment variable.
```

--------------------------------

### Initialize TOFU Database with Custom Path (Python)

Source: https://nauyaca.readthedocs.io/en/latest/how-to/setup-tofu

Demonstrates how to initialize the TOFU database using a custom path in Python. This requires the `pathlib` module and the `TOFUDatabase` class from `nauyaca.security.tofu`.

```python
from pathlib import Path
from nauyaca.security.tofu import TOFUDatabase

# Use custom path
db = TOFUDatabase(Path("/custom/path/tofu.db"))
```

--------------------------------

### Upgrade Nauyaca using pip

Source: https://nauyaca.readthedocs.io/en/latest/installation

Upgrades the Nauyaca package to the latest version using the 'pip install --upgrade' command. This is the standard method for upgrading Python packages when using pip.

```shell
pip install --upgrade nauyaca

```

--------------------------------

### Configure PATH for Nauyaca Installation (Linux/macOS)

Source: https://nauyaca.readthedocs.io/en/latest/installation

Ensures the Python bin directory is included in your system's PATH for the 'nauyaca' command to be recognized. This is crucial after installation, especially when using tools like 'uv'. The configuration can be made permanent by adding it to shell configuration files like .bashrc or .zshrc.

```shell
# For uv tool install
export PATH="$HOME/.local/bin:$PATH"

# Add to ~/.bashrc or ~/.zshrc to make permanent
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

```

--------------------------------

### Install and Configure Filebeat for ELK Stack

Source: https://nauyaca.readthedocs.io/en/latest/how-to/logging

This snippet outlines the steps to install and configure Filebeat for forwarding Nauyaca logs to the ELK Stack. It includes downloading and installing the Filebeat Debian package and providing a sample configuration file (`/etc/filebeat/filebeat.yml`) to ingest JSON logs and send them to Elasticsearch.

```bash
curl -L -O https://artifacts.elastic.co/downloads/beats/filebeat/filebeat-8.11.0-amd64.deb
sudo dpkg -i filebeat-8.11.0-amd64.deb

```

```yaml
filebeat.inputs:
  - type: log
    enabled: true
    paths:
      - /var/log/nauyaca/*.log
    json_keys_under_root: true
    json.add_error_key: true

output.elasticsearch:
  hosts: ["localhost:9200"]
  index: "nauyaca-%{+yyyy.MM.dd}"

setup.template.name: "nauyaca"
setup.template.pattern: "nauyaca-*"

```

```bash
sudo systemctl enable filebeat
sudo systemctl start filebeat

```

--------------------------------

### Configure and Start Server with Middleware

Source: https://nauyaca.readthedocs.io/en/latest/reference/api/server

This snippet demonstrates the core logic within the `start_server` function. It initializes and appends middleware like AccessControl and RateLimiter if configured, creates a middleware chain, and then starts the asyncio server. It supports both standard SSL and PyOpenSSL for TLS.

```python
    # Add access control if configured
    if access_control_config:
        access_control = AccessControl(access_control_config)
        middlewares.append(access_control)
        logger.info(
            "access_control_enabled",
            allow_list=access_control_config.allow_list,
            deny_list=access_control_config.deny_list,
            default_allow=access_control_config.default_allow,
        )

    # Add rate limiting if enabled
    if enable_rate_limiting:
        rate_limiter = RateLimiter(rate_limit_config)
        rate_limiter.start()  # Start cleanup task
        middlewares.append(rate_limiter)
        logger.info(
            "rate_limiting_enabled",
            capacity=rate_limiter.config.capacity,
            refill_rate=rate_limiter.config.refill_rate,
            retry_after=rate_limiter.config.retry_after,
        )

    # Create middleware chain if any middlewares configured
    middleware_chain = MiddlewareChain(middlewares) if middlewares else None

    # Get event loop
    loop = asyncio.get_running_loop()

    # Create server using Protocol pattern
    if use_pyopenssl and pyopenssl_ctx is not None:
        # Use PyOpenSSL TLS wrapper - NO ssl= parameter since TLS is handled manually
        server = await loop.create_server(
            lambda: TLSServerProtocol(
                lambda: GeminiServerProtocol(router.route, middleware_chain),
                pyopenssl_ctx,
            ),
            config.host,
            config.port,
            # NO ssl= parameter - TLS handled by TLSServerProtocol
        )
    else:
        # Standard ssl module
        server = await loop.create_server(
            lambda: GeminiServerProtocol(router.route, middleware_chain),
            config.host,
            config.port,
            ssl=ssl_context,
        )

    logger.info(
        "server_started",
        host=config.host,
        port=config.port,
        document_root=str(config.document_root),
        directory_listing_enabled=enable_directory_listing,
    )

    async with server:
        await server.serve_forever()
```

--------------------------------

### Import Database with Replace Mode

Source: https://nauyaca.readthedocs.io/en/latest/how-to/setup-tofu

Imports a TOML backup file, replacing the entire existing database. This operation is destructive and requires confirmation unless '--force' is used. Ensure you have a backup before proceeding.

```bash
nauyaca tofu import backup.toml --replace
```

--------------------------------

### Run Gemini Fetch Tool

Source: https://nauyaca.readthedocs.io/en/latest/tutorials/building-a-client

Demonstrates how to execute the command-line Gemini fetch tool with different options. It shows basic usage, enabling verbose output, and setting a custom timeout value. This tool requires Python and the nauyaca library to be installed.

```shell
# Basic usage
python gemfetch.py gemini://geminiprotocol.net/

# Verbose output
python gemfetch.py --verbose gemini://geminiprotocol.net/

# Custom timeout
python gemfetch.py --timeout 60 gemini://slow-server.example/

```

--------------------------------

### Start Gemini Server with Configuration (Python)

Source: https://nauyaca.readthedocs.io/en/latest/reference/api

Shows how to configure and start a Gemini server using Nauyaca. It involves loading server configuration from a TOML file using ServerConfig and then initiating the server with start_gemini_server.

```python
from nauyaca.server.config import ServerConfig
from nauyaca.server.protocol import start_gemini_server

# Load configuration
config = ServerConfig.from_toml("config.toml")

# Start server
await start_gemini_server(config)

```

--------------------------------

### Start Server Lifecycle with asyncio

Source: https://nauyaca.readthedocs.io/en/latest/reference/api/server

This Python snippet shows how to initiate the server startup process using the `start_server` function within an asyncio event loop. It loads configuration from a TOML file and runs the server until interrupted.

```python
import asyncio
import signal
from nauyaca.server.config import ServerConfig
from nauyaca.server.server import start_server

async def main():
    config = ServerConfig.from_toml(Path("config.toml"))

    # This runs until Ctrl+C or SIGTERM
    await start_server(config)

if __name__ == "__main__":
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        print("Server stopped by user")
```

--------------------------------

### Uninstall Nauyaca using uv tool

Source: https://nauyaca.readthedocs.io/en/latest/installation

Uninstalls the Nauyaca package using the 'uv tool uninstall' command. This is the procedure for removing the package when managed by the uv tool.

```shell
uv tool uninstall nauyaca

```

--------------------------------

### Upgrade Nauyaca from Source

Source: https://nauyaca.readthedocs.io/en/latest/installation

Upgrades Nauyaca by pulling the latest changes from the main branch of the Git repository and then synchronizing the dependencies. This method is for users who have cloned the source code.

```shell
cd nauyaca
git pull origin main
uv sync

```
Tokens:
Raw