docs for broadlyer + motd + timeout dur

1 files changed, 51 insertions, 0 deletions

diff --git a/layer/broadlayer.ts b/layer/broadlayer.ts
index 03b434c..2f1ccd6 100644
--- a/layer/broadlayer.ts
+++ b/layer/broadlayer.ts
@@ -1,3 +1,46 @@
+/*
+-- broadlayer - http/websocket frontend for broadd
+-- BEOFRE RUNNING:
+------ THIS SERVER OPENS ACCESS TO YOUR PRIVATE IP NETWORK AND LOCALHOST PORTS.
+------ IF THIS IS NOT INTENDED BEHAVIOR, PATCH IT OUT OF THE PROGRAM.
+--
+------ http:
+------ all error replies start with `err_`.
+---------- GET /
+-------------- returns "this is a broadlayer server.", guaranteed
+---------- GET /motd
+-------------- returns the server admin's message of the day. arbitrary size permitted.
+---------- GET /timeout
+-------------- returns the inactivity time after which you will get evicted.
+---------- GET /tcp/connect/<hostname>/<port>
+-------------- creates a broadd tcp connection to the given hostname/ip on the given port. supports ipv4+ipv6.
+-------------- returns `ok_<id>` where id is your unique connection id. store this for polling.
+---------- GET /udp/connect/<hostname>/<port>
+-------------- creates a broadd udp connection to the given hostname/ip on the given port. supports only ipv4.
+-------------- returns `ok_<id>` where id is your unique connection id. store this for polling.
+---------- GET /alive/<id>
+-------------- for telling the server that you are alive. if all is well, server replies with `me too`
+---------- GET /poll/<id>
+-------------- fetch and consume the messages that the server has sent you up to this point. returns an array of buffers
+-------------- format is an array which contains buffers that are strings formatted with each character being an integer.
+-------------- `[ { "type": "Buffer", "data": [ 98, 114, 111, 97, 100, 100 ] } ]` would be `[ "broadd" ]`.
+---------- GET /peek/<id>
+-------------- same as poll, but does not consume the data, allowing you to re-fetch it later.
+---------- GET /close/<id>
+-------------- terminates your connection and deletes your session.
+-------------- replies with "ok" on success.
+---------- POST /send/<id>
+-------------- sends the POST body data to the open socket with the server.
+-------------- replies with "ok" on success.
+---------- GET /tcp/ws/<ip>/<port>
+-------------- connects via tcp to the given server:port and upgrades your connection to websockets.
+---------- GET /udp/ws/<ip>/<port>
+-------------- connects via udp to the given server:port and upgrades your connection to websockets.
+------ websocket:
+---------- the websocket connection behaves exactly like a plain connection to the server would.
+---------- only difference is a special command "ping", which returns "pong" and nothing is relayed to the target server.
+*/
+
 import { dns, randomUUIDv7 } from "bun"
 
 if (process.argv.length < 4) {
@@ -205,6 +248,8 @@ Bun.serve({
     hostname: server_ip,
     routes: {
         '/': new Response('this is a broadlayer server.'),
+        '/motd': new Response('default message-of-the-day!'),
+        '/timeout': new Response(eviction_timeout.toString()),
         '/tcp/connect/:ip/:port': async req => {
             const port = parseInt(req.params.port)
             if (isNaN(port)) return new Response('err_badport')
@@ -242,6 +287,12 @@ Bun.serve({
             console.log('clients:' + Object.keys(sessions).length)
             return new Response('ok_' + res)
         },
+        '/alive/:id': async req => { // heartbeat
+            const sess = sessions[req.params.id]
+            if (!sess) return new Response('err_badid')
+            sess.lastSeen = Date.now()
+            return new Response('me too')
+        },
         '/poll/:id': async req => { // read and consume queue
             const sess = sessions[req.params.id]
             if (!sess) return new Response('err_badid')