Structure and request flow

HarvTTP combines a small cooperative scheduler, a preloaded asset bundle, a minimal packet stack, a PHP request queue and an HNET MMIO driver. The current runtime is deliberately compact so the processor and boot behavior remain visible.

Boot-ROM handoff

The boot ROM validates harvttp.elf, loads executable segments into IMEM, data segments into DMEM, creates start parameters and optionally places a content bundle in DMEM. At application entry:

a0 = address of harvos_app_start_params_t
sp = 0x00178000
pc = ELF entry point
IMEM loader = locked

Start parameters

Field	Use in HarvTTP
`app_id`	Mixed into the local MAC address: `02:48:54:54:50:app_id`.
`service_mask`	Reserved for later service policy.
`debug_flags`	Reserved for diagnostics and telemetry.
`preloaded_content_vaddr`	Address of the HTTP bundle prepared by the boot ROM.
`preloaded_content_size`	Bundle size, checked against the bundle header.
`config_path`	Documents the YAML configuration source.
`data_path`	Documents the persistent data path used by the service.
`content_root_path`	Documents the program-image web root path.

Internal structures

Type	Purpose
`harvttp_context_t`	Main runtime state: start parameters, workers, network state, TCP peers, bundle pointers, PHP jobs, SQL loopback sockets, buffers and counters.
`harvttp_thread_t`	Cooperative worker with active/running flags, wake tick, fault counters and a run function.
`harvttp_net_t`	MAC address, IP, mask, gateway, DNS, DHCP server, DHCP XID and DHCP state.
`harvttp_tcp_peer_t`	Client MAC/IP/port, sequence numbers, last tick and TCP state for up to 64 peers.
`harvttp_tx_queue_t`	64 slots for outgoing Ethernet frames, which prevents short response bursts from being dropped immediately.
`harvttp_http_job_t`	Queued PHP request with URI, query string, POST body, peer index and response buffers.
`harvos_http_bundle_entry_t`	One entry per preloaded file: path, offset, size and MIME type.

Cooperative workers

ID	Name	Task	Wake behavior
0	Content	Validates the bundle, finds `/index.html` and prepares fallback output.	Runs rarely after initialization.
1	DHCP	Sends DHCP Discover/Request and manages the bound state.	Short sleeps until a lease is acquired.
2	TX	Flushes the outgoing frame queue to HNET.	One tick while work exists, otherwise two ticks.
3	RX/HTTP	Receives bursts, dispatches ARP/DHCP/TCP and routes HTTP requests.	One to two ticks in normal operation.
4	Watchdog	Publishes telemetry through the HarvOS syscall path and restarts faulted workers.	4096 ticks.
5	SQL loopback	Maintains the HarvSQL loopback client path used by PHP database calls.	Fast while connecting, slow while idle.
6-9	HTTP workers	Consume queued PHP jobs, stream heartbeats for long requests and send completed responses.	One tick while busy, longer sleeps while idle.

HTTP request flow

HNET reports RX_VALID.
HarvTTP copies the Ethernet frame out of the DMA window into the RX buffer.
ARP requests for the assigned IP are answered.
DHCP replies are processed until the network is bound.
A TCP SYN to port 80 creates a peer and returns SYN/ACK.
The HTTP parser accepts GET and selected POST data up to the configured request buffer.
Static paths are resolved against the preloaded bundle or data web root.
.php paths are queued as harvttp_http_job_t entries when PHP support is enabled.
The response uses HTTP/1.0 and Connection: close.

PHP execution path

HarvTTP has two PHP paths. The small template renderer remains useful for smoke tests and diagnostics. The PHP 8.5 path builds a harvos_php85_request_t and calls the HarvOS SAPI so Zend executes the script from a memory-backed stream. Four HTTP workers can keep independent request jobs in flight; the Zend lane still depends on the linked PHP build and the available HarvOS runtime layer.

Feature	Current behavior
Output	Buffered into HarvTTP-owned memory, with heartbeat streaming for long-running PHP requests.
Headers	Captured by the SAPI and translated back into the HTTP response.
Request data	URI, script name, query string, server fields, cookies and POST bytes are passed through the ABI.
Database	PHP database calls target HarvSQL through the loopback socket path on the MySQL-compatible port.

Path and MIME rules

Rule	Description
`/`	Resolves to `/index.html` or to the configured PHP entry point in a WordPress data web root.
Trailing slash	`/docs/` resolves to `/docs/index.html` when the path buffer allows it.
Query/fragment	The path resolver ignores everything after `?` or `#`.
Traversal	`.` and `..` are normalized; paths escaping above `/` are rejected.
MIME	HTML, CSS, JS, images, text, PHP and binary data are classified before response generation.