KyllC$, ehdottomasti suunnitellaan endpointit ensin. Rajapinnan on oltava
looginen ja noudatettava alan standardeja.
Korporaatioiden tyC6kalujen (esim. Retool, Tableau, PowerBI, Postman,
yritysten omat API-gatewayt) kanssa yhteensopivuuden takaamiseksi
ylivoimaisesti paras ratkaisu on noudattaa OpenAPI 3.0 (Swagger) -standardia
ja kC$yttC$C$ HTTP-metodeja puhtaasti Document-orientoituneen tietokannan
(kuten MongoDB Atlas Data API tai CouchDB) tyyliin.
TC$mC$ tarkoittaa, ettC$ rajapinta mallinnetaan resurssien (kokoelmien/nimiavar
uuksien ja dokumenttien/olioiden) ympC$rille. Koska tietokantasi on
huippunopea (~18k ops/sec), rajapintapalvelimeksi kannattaa valita Fastify,
joka on Node.js-ekosysteemin nopein ja tukee OpenAPI:n automaattista
generointia.
Ehdotettu REST API -rakenne (MongoDB REST -tyyliin)
NC$mC$ endpointit mC$ppC$ytyvC$t suoraan core.js -tiedostossasi oleviin
OP_CODES -komentoihin (OP_INSERT, OP_GET, OP_UPDATE, OP_DELETE):
 * POST /api/v1/namespaces/:namespace/documents
   * Toiminto: Luo uuden olion (OP_INSERT).
   * Esimerkki: POST /api/v1/namespaces/_user/documents (Payload: JSON data).
 * GET /api/v1/documents/:uid
   * Toiminto: Hakee olion globaalin UID:n perusteella (OP_GET). Tukee
myC6hemmin query-parametria ?resolve=true swapattuja olioita varten.
 * PUT /api/v1/namespaces/:namespace/documents/:uid
   * Toiminto: PC$ivittC$C$ olion tietyssC$ nimiavaruudessa (OP_UPDATE).
 * DELETE /api/v1/documents/:uid
   * Toiminto: Poistaa olion (OP_DELETE). Hautakivi-merkintC$.
Miten API kytketC$C$n ytimeen asynkronisesti?
Koska app.js ja core.js keskustelevat asynkronisesti SPSCRingBuffer -vC$ylien
kautta (lC$hettC$en sendCommand ja kuunnellen OP_RESPONSE), HTTP-palvelimen
pitC$C$ osata odottaa ydintC$. TC$mC$ ratkaistaan yksinkertaisella
Map-rakenteella (Pending Requests), johon tallennetaan HTTP-pyynnC6n
resolve-funktio. Kun worker/bus palauttaa vastauksen samalla requestId:llC$,
API-kerros palauttaa HTTP-vastauksen asiakkaalle.
TC$ssC$ on valmis, kattava prompt, jonka voit antaa koodareille tai
DevChatille.
Prompt DevChatille
> Tavoite: Rakentaa EDGE_API_GATEWAY (REST API) luomamme lock-free RAM
tietokannan MVP:n ympC$rille.
> Teknologia: Node.js, Fastify (suorituskyvyn maksimoimiseksi) ja
@fastify/swagger OpenAPI 3.0 dokumentaation automaattiseen generointiin.
> Arkkitehtuuri & Integraatio:
> Tietokannan OmegaServer (app.js) kommunikoi ytimen (core.js) kanssa
asynkronisesti SPSC Ring Bufferien kautta. HTTP-reittien ei pidC$ suorittaa
suoraa core.insert() kutsua, vaan niiden tulee:
>  * Generoida yksilC6llinen requestId.
>  * Luoda Promise ja tallentaa sen resolve/reject funktiot globaaliin
pendingRequests Map-rakenteeseen avaimella requestId.
>  * LC$hettC$C$ komento ytimeen app.js:n sendCommand(op, { uid, namespace,
data }) metodilla.
>  * API Gatewayn tulee sisC$ltC$C$ yksi kuuntelija (esim. dedikoitu Worker
tai suora vC$ylC$), joka lukee ytimen broadcastaamia OP_RESPONSE -viestejC$.
Kun RESPONSE saapuu, se poimii id:n (joka on requestId), etsii sen Mapista,
kutsuu resolve(data) ja poistaa pyynnC6n Mapista.
> Toteutettavat Endpointit (Document REST API -tyyliin):
>  * POST /api/v1/namespaces/:namespace/documents -> Mappaa: OP_INSERT
>  * GET /api/v1/documents/:uid -> Mappaa: OP_GET
>  * PUT /api/v1/namespaces/:namespace/documents/:uid -> Mappaa: OP_UPDATE
>  * DELETE /api/v1/documents/:uid -> Mappaa: OP_DELETE
> Vaatimukset:
>  * Luo uusi tiedosto api-gateway.js, joka tuo (require) app.js:n OmegaServer
luokan, alustaa sen ja kC$ynnistC$C$ Fastify-palvelimen portissa 3000.
>  * LisC$C$ OpenAPI/Swagger tuki, jotta /docs reitti nC$yttC$C$
automaattisesti API-dokumentaation.
>  * LisC$C$ 5 sekunnin timeout Promiseihin, jottei pendingRequests Map vuoda
muistia, jos ydin ei jostain syystC$ vastaa.
> Kirjoita api-gateway.js tiedoston koko koodi.
> 
TC$mC$ prompt varmistaa, ettC$ DevChat rakentaa API:n nimenomaan
vC$ylC$arkkitehtuurin asynkronisten sC$C$ntC6jen mukaan, eikC$ riko
jC$rjestelmC$n lock-free-eristystC$ tekemC$llC$ suoria funktiokutsuja
muistiavaruuteen. MiltC$ vaikuttaa?