# Host your Glop’s game server

Glop can host your client while you run the multiplayer world and saved data on
your own public HTTPS server. This optional capability uses bounded JSON requests
and polling. For general HTTPS and WebSocket access on public production, see
the Internet section of SDK.md. Direct browser networking stays restricted.

## Upload

Add `glop.json` at the root of your ordinary upload:

```json
{"homeserver":"https://game.example.com"}
```

Use one lowercase HTTPS origin with no trailing slash, path, query, credentials,
or custom port. IP literals, local names, and Glop’s own domains are rejected.
The server is fixed to that uploaded bundle. Updating it creates a new bundle and
requires fresh player consent. Existing Glops need no manifest or changes.

Include the current `/glop-sdk.mjs` with your files:

```js
import {createGlop} from './glop-sdk.mjs';
const glop = createGlop();
// The player must first use Glop’s own Connect control.
const world = await glop.homeserver.request({action:'poll'});
```

The host shows the declared domain and an explicit connection confirmation.
Code cannot approve its own connection. Requests are rejected before consent;
no request to the homeserver is made by preloading or merely viewing the game.
Disconnect, navigating away, hiding the tab, or expiration clears that mount’s
consent. Reconnecting requires another click. Consent expires after 30 minutes.
The client should handle errors and show a reconnect instruction. In-flight
server work may already have happened when the player disconnects; Stop cannot
undo a move. Give writes an idempotency key or expected revision.

## Server protocol

First upload a draft to obtain its project ID. Serve this public opt-in document
at `GET /.well-known/glop.json` with `Content-Type: application/json`:

```json
{"version":1,"projects":["YOUR-GLOP-PROJECT-ID"]}
```

List only the Glop projects you want to serve (maximum 100). Glop checks it on
every connection. A malformed, redirected, unavailable, or non-opted-in server
fails closed. This document is public configuration, not a secret.

Accept `POST /glop` with JSON:

```json
{"version":1,"project":"PROJECT-ID","player":"RANDOM-CONNECTION-ID","value":{"action":"poll"}}
```

Return your game's JSON value, with `Content-Type: application/json` and a 2xx
status. That value becomes the result of `glop.homeserver.request(...)`. Glop
discards upstream headers and treats the body as data; use textContent for text.
The player ID is random per connection, not a Glop account ID, and is not proof
of an authenticated account. It changes after reconnect. Implement your own game
sessions/authentication if you need durable player identity; never put server
secrets in the uploaded client. Validate game rules on your server.

The server must be reachable on public HTTPS with a valid certificate. No CORS
configuration is needed: Glop relays these requests from its server, not from the
player’s browser. Glop does not forward browser cookies, account authorization,
CSRF tokens, or caller-selected headers. Network infrastructure may add its own
transport headers. Do not treat any transport header as proof of player identity.

Limits: 16 KiB per client JSON value, 64 KiB per response, 5 seconds per upstream
request, one outstanding request per mount, 120 operations/minute per signed-in
player across their Glops, 10 connections/minute per player, 6,000 upstream
operations/minute per server origin, four unexpired grants per browser session.
Use roughly 1–2 second polling. Invalid/rate-limited requests can also consume the
request allowance. Your service still needs its own request limits and backups.

## Isolation and hosting assumptions

The uploaded iframe retains its opaque origin and restrictive CSP. The host
checks the exact mounted frame and channel, keeps the consent grant private,
and rejects background requests. The relay rechecks session, bundle access,
beta access and grant expiry; logout and bundle deletion invalidate grants.
It uses fixed paths, constructs outbound requests from scratch, refuses redirects,
and enforces response type, byte and time limits.

On the production VPS, homeserver requests use the same DNS-validated, pinned
HTTPS transport as the Internet SDK. Private/reserved addresses and the Glop
server are rejected, cookies are omitted, and redirects are refused. The
separate Sites deployment uses Workers public Internet fetch without private
network bindings. See SDK.md for general Internet access on production.

This does not make a creator’s service trustworthy or permanently available.
It receives game data the client sends and controls that data’s storage. The
existing best-effort CPU/lifecycle guard is not a hard resource sandbox.

## Runnable example

Download `/examples/homeserver/index.html` and `/glop-sdk.mjs` into your upload
folder and add the manifest above with your own domain. Run
`/examples/homeserver/server.mjs` on your server after setting `GLOP_PROJECT_ID`.
See `/examples/homeserver/README.md` for setup. The shared garden example checks
move revisions and saves its world to disk, so two players can plant together.