Executing a serverless function

Oyster comes with a HTTP gateway by default accessible at oyster.run.

Mapping subdomains

The gateway accepts any requests sent to <subdomain>.oyster.run and uses the subdomain to fetch the code to be executed. The subdomain is expected to be the tx hash of the code tx encoded using Base32 without any padding.

For example, to send requests to the code in tx hash 0x2c9eb7c03d2062516ca0a828c84b3a87d0365c47f71d326ea196f91031eefcac, you would need to send it to FSPLPQB5EBRFC3FAVAUMQSZ2Q7IDMXCH64OTE3VBS34RAMPO7SWA.oyster.run.

Perfect forwarding

The gateway aims to perfectly forward requests that it receives to the serverless function. This includes the URI path, URI query, HTTP method, HTTP headers, HTTP body, etc. This is in turn available inside the workerd runtime and can be handled by the serverless function. The same applies to the response as well.

Example request

Here is an example request being sent to the factorization function.

$ curl FSPLPQB5EBRFC3FAVAUMQSZ2Q7IDMXCH64OTE3VBS34RAMPO7SWA.oyster.run -d '{"num": 60000}' -v
*   Trying <redacted>:80...
* Connected to FSPLPQB5EBRFC3FAVAUMQSZ2Q7IDMXCH64OTE3VBS34RAMPO7SWA.oyster.run (<redacted>) port 80 (#0)
> POST / HTTP/1.1
> Host: FSPLPQB5EBRFC3FAVAUMQSZ2Q7IDMXCH64OTE3VBS34RAMPO7SWA.oyster.run
> User-Agent: curl/7.81.0
> Accept: */*
> Content-Length: 14
> Content-Type: application/x-www-form-urlencoded
> 
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< Server: nginx/1.18.0 (Ubuntu)
< Date: Mon, 25 Dec 2023 05:29:56 GMT
< Content-Type: text/plain;charset=UTF-8
< Content-Length: 19
< Connection: keep-alive
< x-oyster-signature: 37ca998deec540de877833274f46f11b4e814341edb05dd3d41e66aac806cf714fcb1558677ab9374caa45021f87189101b5cd2cc3bdb4b9f1e65f17f6880ed31b
< x-oyster-timestamp: 1703482196
< 
* Connection #0 to host FSPLPQB5EBRFC3FAVAUMQSZ2Q7IDMXCH64OTE3VBS34RAMPO7SWA.oyster.run left intact
2,2,2,2,2,3,5,5,5,5

The function successfully executes and returns the factors in the response.