The Spartan Protocol¶

This document explains what the Spartan protocol is, why it exists, and how it compares to similar protocols.

What is Spartan?¶

Spartan is a simple, text-focused internet protocol designed for serving lightweight content. It's similar to Gemini but even simpler—it removes the complexity of TLS while adding native support for content uploads.

Design philosophy¶

Spartan embraces minimalism:

No encryption by default - Reduces complexity and barrier to entry
Single-digit status codes - Only 4 possible responses
Native uploads - Content submission is part of the core protocol
Plain text focus - Optimized for text content (especially Gemtext)

Protocol format¶

Request format¶

A Spartan request is a single line:

host path content-length\r\n[data]

Component	Description
`host`	The server hostname
`path`	The requested path (URL-encoded)
`content-length`	Length of upload data (0 for GET requests)
`[data]`	Optional upload data

Examples:

# GET request (no body)
example.com / 0\r\n

# Upload request (with body)
example.com /upload.txt 13\r\nHello, world!

Response format¶

A Spartan response starts with a status line:

status meta\r\n[body]

Component	Description
`status`	Single digit (2, 3, 4, or 5)
`meta`	Meaning depends on status code
`[body]`	Response content (only for status 2)

Status codes¶

Spartan uses only four status codes:

Code	Name	Meta contains	Body
2	Success	MIME type	Content
3	Redirect	Target URL	None
4	Client error	Error message	None
5	Server error	Error message	None

This simplicity means:

Clients only need to handle 4 cases
No ambiguity about response handling
Easy to implement correctly

Comparison with Gemini¶

Feature	Spartan	Gemini
Encryption	None	Mandatory TLS
Client certificates	No	Yes (for auth)
Status codes	4 (single digit)	6 categories (two digits)
Uploads	Native support	Requires input prompt
Default port	300	1965
TOFU validation	No	Yes
Complexity	Lower	Higher

When to choose Spartan¶

Internal networks - Where encryption isn't needed
Upload-heavy applications - Native upload support is cleaner
Learning/education - Simpler protocol is easier to understand
Embedded systems - Lower resource requirements

When to choose Gemini¶

Public internet - Encryption protects privacy
User authentication - Client certificates provide identity
Security-sensitive content - TLS provides integrity

Content types¶

While Spartan can serve any MIME type, it's optimized for:

text/gemini (Gemtext) - The preferred format
text/plain - Simple text documents
Other formats - Images, binaries, etc. work fine

Gemtext format¶

Gemtext is a simple markup format:

# Heading
## Subheading

Regular paragraph text.

=> /link Link text
=> spartan://example.com/ External link

* List item 1
* List item 2

> Quoted text

```preformatted
code block

## Upload mechanism

Spartan's upload mechanism is elegant:

1. Client sends request with `content-length > 0`
2. Server reads exactly `content-length` bytes after the request line
3. Server processes the upload and responds

**Special case: Deletion**

A zero-byte upload to an existing resource signals deletion:

example.com /old-file.txt 0\r\n ```

Servers may choose to support this or return an error.

Port 300¶

Spartan uses port 300 by default. This was chosen because:

It's a memorable, round number
It's in the privileged range (requires root on Unix)
It doesn't conflict with common protocols

For development, use a high port like 3000.

Security considerations¶

Since Spartan doesn't use encryption:

Don't transmit sensitive data over Spartan
Use on trusted networks only
Consider a reverse proxy with TLS for public access
Access control can restrict who can connect