HTTP Reference

HTTP

RiptOPL can read a game library straight off an ordinary HTTP server: a small games.csv catalog says what exists, and the console streams the ISO itself with plain HTTP byte ranges as the game asks for sectors. The server must satisfy the client profile: no transfer encoding, no content encoding other than identity, no multipart responses, exact Content-Range and Content-Length for range reads, and complete response bodies. Check it with the conformance tool.

Use HTTP only on a trusted, isolated local network. It provides no encryption or server/content authentication; range and length validation detect malformed responses, not substituted game data.

The design, the byte-range reader RiptOPL follows, and the PC server are Docmine17's (Open-PS2-Loader-HTTP).

His unmodified server is the compatibility baseline. If you already run it, RiptOPL points at it as-is: same port, same games.csv, same folder layout. No new API, no catalog conversion, no regeneration step, nothing to upgrade.

---

Status

Implemented and host-tested, not yet verified on PlayStation 2 hardware. Every part below exists in the build, but none of it has run on a PlayStation 2. Treat HTTP as a development feature until that changes.

Part	State
Catalog fetch and parse	done, and cross-checked against a reference parser
Byte-range validation	done, and covered by host tests
Network settings, Test action	written, not hardware-tested
Game list, artwork, per-game settings	written, not hardware-tested
Launching a game	written, not hardware-tested — this is the least proven part
DVD9 (dual layer)	probe implemented, never seen a real dual-layer read
Virtual memory cards	deliberately unavailable
Neutrino, PS1/VCD, Ember	deliberately unavailable
ZSO / compressed images	listed, refused by name

---

Setting it up

On the PC, run an HTTP server meeting the profile above, with your ISOs under its document root, and put a games.csv beside them. Docmine17's http_server.py does exactly this and defaults to port 1100.

On the console, set Network Connectivity to Manual or Auto in Game Sources, then open Settings → Network:

Row	What it is
Protocol	choose HTTP
HTTP server	the PC's IPv4 address
HTTP port	1100 by default; anything valid works, 80 and 8080 included
HTTP base path	/ unless your catalog and images live in a subfolder
Test HTTP server	fetches the catalog, parses it, and reads one real byte range

Use Test before saving. It reports whether the server is unreachable, the catalog request fails, the catalog has entries but no supported ISO, or the server does not return the exact bytes requested.

Quick start: actually launching a game

Once Test HTTP server passes with a non-empty catalog:

1. Save or leave Settings with the HTTP values active.
2. Open the HTTP Games page from the main menu. If Network Connectivity is Manual, opening the page starts the connection; Auto starts it at boot.
3. Pick a title from the catalog and launch it normally. HTTP always uses RiptOPL's native <OPL> core; the global Default Loader Core does not turn HTTP into a Neutrino launch.
4. If the HTTP page is empty, re-run Test HTTP server first. A successful empty-catalog test only proves the server is reachable; it does not give the menu a game to list.

The server does not need a writable share. The menu reads games.csv, and the in-game HTTP driver requests sectors from the ISO with byte ranges.

An empty catalog is a valid answer, and Test says so plainly: it proves the server is there, and proves nothing at all about whether byte ranges work.

The first protocol selected while the adapter is unused can start immediately. Switching away from an already loaded protocol requires restarting RiptOPL; the settings page offers to save and restart on the spot (and again on the Network page's OK), and Save Settings offers it too. Only one protocol can own the adapter in a session.

---

The catalog

games.csv at the root of your base path, one game per line:

SLUS_123.45,Example Game,DVD,DVD/Example Game.iso
SLUS_200.01,"Example, The",DVD,DVD/example-the.iso
SLES_512.34,Short One,CD,CD/Short One.iso

STARTUP,TITLE,MEDIA,PATH — the boot identifier, the name shown on screen, CD or DVD, and the path to the image relative to your base path. The title and the filename need not resemble each other.

Older catalogs keep working untouched. These are all still accepted:

# Filename derived from the title; media defaults to DVD
SLUS_123.45,Example Game
# Explicit media
SLUS_200.02,Another Game,CD
# Extension already on the title, not doubled
SLUS_300.03,Already Has Ext.iso,CD
# Startup only; it doubles as title and filename
SLUS_400.04

Blank lines and lines starting with # are ignored. Both LF and CRLF work, and a missing final newline is fine. A field containing a comma or a quote can be double-quoted, "" being a literal quote.

A row RiptOPL cannot use is skipped and the rest of the library still loads — one typo does not cost you every game. What gets a row skipped: no startup ID, a startup longer than 12 characters, a media field that is not exactly CD or DVD, a path that escapes your base directory, an absolute URL, or a filename that is not an image.

If a row names a path explicitly, that path is what gets requested. It is never quietly retried under a name derived from the title — that is how you end up launching a different disc than the one you picked.

---

What works, and what does not

Feature	Over HTTP
PS2 ISO, CD and DVD5	the supported target
DVD9	implemented, unproven — see Status
Per-game settings, artwork, cheats	yes, stored locally (see below)
Favourites, last played	yes
Saving to a physical memory card	yes
Virtual memory cards	no — nothing writes to the server, so there is nowhere to keep one
Neutrino core	no — it would need its own HTTP backend
PS1 / VCD / Ember	no
ZSO and other compressed images	no — they are listed but refuse to launch
HTTPS, passwords, redirects	no — this is plain LAN HTTP

The PS2 logo animation is skipped on HTTP launches. Checking it means reading the logo out of the image through a file handle, and HTTP has no filesystem to open one on.

Where per-game data lives

Folder-based sources keep CFG/, ART/ and CHT/ under the configured library prefix; APA uses its selected PFS data home. HTTP cannot: the server is read-only and there is no drive to write to. So HTTP keeps them with your settings instead — under RiptOPL’s active local settings home (boot-directory/discovery or Custom Settings Path).

That is the one deliberate exception to the usual rule, and it is why covers and per-game options for HTTP games go next to settings_riptopl.cfg rather than on the server.

---

When something goes wrong

RiptOPL refuses rather than guesses. A read is only accepted when the server returns exactly the bytes that were asked for: the right status, the right byte interval, and the right length. A server that ignores the range, answers a different interval, or stops early gets a disc read error instead of quietly feeding the game whatever arrived.

What you see	What it means
Cannot reach the HTTP server	wrong address or port, or the server is not running
games.csv is missing, unreadable or too large	the catalog did not arrive intact
The server did not return the exact bytes	the server does not support byte ranges properly
Compressed images are not supported	the row points at a .zso

If the server disappears mid-game, the console retries the same read once on a fresh connection and then reports a disc error. It will not sit there reconnecting forever.

---

Notes for anyone changing this code

• src/httpcatalog.c and pc/http/catalog_reference.py are one contract. The fixtures in pc/http/fixtures/ hold them to it and pc/http/tests/compare_catalog.py proves it. Change one, change all three, in the same commit.
• Run the host tests. sh pc/http/tests/run.sh compiles the real sources and exercises the parsers directly — header framing, range validation, truncation, and every catalog fixture in three line-ending forms.
• modules/network/common/httpstream.inc is shared by the menu RPC module and the in-game cdvdman driver. Both IRX rules depend on it in the top-level Makefile, because make cannot see inside a sub-make and a stale IRX otherwise builds clean locally and fails CI.
• The two lwIP stacks are not interchangeable. MSG_DONTWAIT is 0x08 on the menu path and 0x40 in SMSTCPIP, and SMSTCPIP exports no select, so the in-game reader polls against a deadline instead.
• docs/HTTP-INTEGRATION-PLAN.md carries the phase ledger, the evidence table and the console test matrix. Read it before picking this up.

---

Credits

• Docmine17 — the HTTP design, the byte-range reader this port follows, and the PC server.

Related guide: HTTP.

---

Source: docs/HTTP.md @ d2c64674ea98.