Crate guppy_protocol 

An implementation of the Guppy protocol v0.4.4 (guppy://, UDP port 6775): an async client and server with chunking, per-packet acknowledgement, and retransmission, plus a small CLI.

Guppy is dimkr’s smolweb-over-UDP protocol, inspired by TFTP, DNS, and Spartan. A request is a single datagram carrying a URL (user input rides the query component, percent-encoded). The server answers with either a special single-digit packet — 1 <prompt> / 3 <url> redirect / 4 <error> — or a success packet <seq> <mimetype>\r\n<data> whose sequence number starts at a random value in [6, 2^31-1], followed by continuation packets <seq>\r\n<data> (seq incrementing by one), ended by an empty continuation (the end-of-file packet). The client acknowledges every success/continuation/EOF packet by echoing its sequence number. Lost packets are handled by retransmission on both sides.

This crate is independent and unaffiliated with the protocol’s author. The crates.io name is qualified (guppy-protocol) because the bare guppy name is used by an unrelated project.

use guppy_protocol::{GuppyResponse, fetch};

match fetch("guppy://guppy.mozz.us/", &Default::default()).await? {
    GuppyResponse::Success { mime, body } => {
        println!("{} bytes of {mime}", body.len());
    }
    other => println!("{other:?}"),
}

Structs

FetchOptions

Options for a fetch.

FileHandler

A static-directory Handler: gemtext-first, index.gmi per directory, traversal-protected, prompt input ignored.

Request

One guppy request, as handed to a Handler.

ServerConfig

Server tuning.

Enums

ClientError

Why a fetch failed before a GuppyResponse was obtained.

GuppyResponse

A complete guppy response, as returned by the client.

Packet

A parsed server→client packet.

Constants

GUPPY_PORT

Guppy’s default port (‘gu’).

MAX_REQUEST_BYTES

The spec’s request-size ceiling: the URL plus the trailing CRLF must fit in 2048 bytes.

MAX_SEQ

The largest sequence number (maximum value of a signed 32-bit integer).

MIN_SEQ

The smallest first-packet sequence number.

Traits

Handler

The application seam: turn a Request into a GuppyResponse. Success bodies are chunked, transmitted, and retransmitted by the server; the other variants go out as single special packets.

Functions

fetch

Fetch a guppy:// URL. User input goes in the URL’s query component, percent-encoded (the input-prompt flow: a GuppyResponse::Prompt answer means “repeat the request with input attached”).

parse_packet

Parse a server→client packet.

serve

Serve guppy on socket through handler until shutdown resolves.