Merge pull request #9 from i5heu/stream-prototype

Make stream-prototype the main state

Author: i5heu

.gitignore

@@ -1,2 +1,3 @@
 main
-*.log
+*.log
+data/

README.md

@@ -1,18 +1,130 @@
- [![Go Reference](https://pkg.go.dev/badge/github.com/i5heu/ouroboros-db.svg)](https://pkg.go.dev/github.com/i5heu/ouroboros-db) [![Tests](https://github.com/i5heu/OuroborosDB/actions/workflows/go.yml/badge.svg?branch=main)](https://github.com/i5heu/OuroborosDB/actions/workflows/go.yml) ![](https://github.com/i5heu/OuroborosDB/blob/gh-pages/.badges/main/coverage.svg) [![Go Report Card](https://goreportcard.com/badge/github.com/i5heu/ouroboros-db)](https://goreportcard.com/report/github.com/i5heu/ouroboros-db) [![wakatime](https://wakatime.com/badge/github/i5heu/ouroboros-db.svg)](https://wakatime.com/badge/github/i5heu/ouroboros-db)
- 
-<p align="center">
-  <img src=".media/logo.jpeg"  width="300">
-</p>
+# OuroborosDB
 
-⚠️ This Project is still in development and not ready for production use. ⚠️
+[![Go Reference](https://pkg.go.dev/badge/github.com/i5heu/ouroboros-db.svg)](https://pkg.go.dev/github.com/i5heu/ouroboros-db) [![Tests](https://github.com/i5heu/OuroborosDB/actions/workflows/go.yml/badge.svg?branch=main)](https://github.com/i5heu/OuroborosDB/actions/workflows/go.yml) ![Coverage badge](https://github.com/i5heu/OuroborosDB/blob/gh-pages/.badges/main/coverage.svg) [![Go Report Card](https://goreportcard.com/badge/github.com/i5heu/ouroboros-db)](https://goreportcard.com/report/github.com/i5heu/ouroboros-db) [![wakatime](https://wakatime.com/badge/github/i5heu/ouroboros-db.svg)](https://wakatime.com/badge/github/i5heu/ouroboros-db)
 
-# OuroborosDB
+![OuroborosDB logo](.media/logo.jpeg)
+
+⚠️ This Project is still in development and not ready for production use. ⚠️
 
 ## Name and Logo
 
 The name "OuroborosDB" is derived from the ancient symbol "Ouroboros," a representation of cyclical events, continuity, and endless return. Historically, it's been a potent symbol across various cultures, signifying the eternal cycle of life, death, and rebirth. In the context of this database, the Ouroboros symbolizes the perpetual preservation and renewal of data. While the traditional Ouroboros depicts a serpent consuming its tail, our version deviates, hinting at both reverence for historical cycles and the importance of continuous adaptation in the face of change.
 
 ## License
+
 OuroborosDB (c) 2024 Mia Heidenstedt and contributors  
-   
+ 
 SPDX-License-Identifier: AGPL-3.0
+
+## HTTP API
+
+The reference server in `cmd/server` now exposes a lightweight HTTP API on port 8083. Start the binary and the REST endpoints below become available.
+
+### `POST /data`
+
+Create a new stored object. The body must be JSON with the payload content encoded as base64. Reed-Solomon parameters default to 4 data shards and 2 parity shards when omitted. Provide an optional `mime_type` (<=255 bytes) to mark binary data; absence of a MIME type treats the payload as UTF-8 text.
+
+```json
+{
+  "content": "aGVsbG8gd29ybGQ=",
+  "reed_solomon_shards": 4,
+  "reed_solomon_parity_shards": 2,
+  "mime_type": "application/octet-stream"
+}
+```
+
+Successful requests respond with the SHA-512 key of the stored data:
+
+```json
+{
+  "key": "<hex-encoded-hash>"
+}
+```
+
+### `GET /data`
+
+List all stored keys returned as hexadecimal-encoded hashes:
+
+```json
+{
+  "keys": ["<hex-encoded-hash>" ]
+}
+```
+
+### Try it
+
+```bash
+curl -X POST http://localhost:8083/data \
+  -H 'Content-Type: application/json' \
+  -d '{"content":"aGVsbG8=","reed_solomon_shards":4,"reed_solomon_parity_shards":2}'
+
+curl http://localhost:8083/data
+```
+
+### `GET /data/{key}`
+
+Retrieve a stored entry by its hexadecimal hash. The response includes a base64 encoded payload, the inferred text flag, and the MIME type (if supplied when writing).
+
+```json
+{
+  "key": "<hex-encoded-hash>",
+  "content": "aGVsbG8gd29ybGQ=",
+  "is_text": true,
+  "mime_type": ""
+}
+```
+
+### Payload header format
+
+Stored objects reserve the first 256 bytes for metadata:
+
+- Byte `0`: the most significant bit (MSB) marks text payloads. When set (`1`), the payload is treated as UTF-8 text and no MIME is stored.
+- Bytes `1-255`: when the MSB is `0`, these bytes contain an ASCII/UTF-8 MIME type string padded with zeros. Empty or whitespace-only MIME values fall back to text handling.
+- Remaining bytes: the original payload content.
+
+This layout allows fast retrieval of text/binary hints without additional metadata calls.
+
+
+## Development Notes
+
+### Legend
+
+#### Annotation legend for function comments:
+To indicate the correctness and safety of the logic of functions, the following annotations are used in comments directly after the function definitions (See examples below):
+
+- `// A` - Function and was written by **AI** and was not reviewed by a **human**.
+- `// AP` - Function was written by **AI** and was reviewed but the **human** has found a potential issue which the **human** marked with a `// TODO ` comment.
+- `// AC` - Function was written by **AI** and was reviewed and approved by a **human** that has medium confidence in the correctness and safety of the logic.
+- `// H` - Function was written by a **human**
+- `// HP` - Function was written by a **human** but the **human** has found a potential issue which the **human** marked with a `// TODO ` comment.
+- `// HC` - A **human** comprehended the logic of th function in all its dimensions and is confident about its correctness and safety.
+
+If the function has a higher risk profile (e.g., involves complex algorithms, security-sensitive operations, or critical data handling), a `P` prefix is added for `Priority`:
+
+**All `P` function must be brought to `PHC` status before a production release.**
+
+We add the indicators directly after the function declaration, although it is normally not common practice in Go, because it makes it easier to see the status of the function for most editors as they show use sticky function declaration.
+
+Examples:  
+```go
+
+// This function does X, Y, and Z.
+func exampleFunction() { // A
+    // Function is low risk and was written by AI and not reviewed by a human.
+}
+
+// This function does X, Y, and Z.
+func exampleFunction() { // HC
+    // Function is low risk and was comprehended by a human who is confident about its correctness and safety.
+}
+
+// This function performs critical operations X, Y, and Z has some funky stuff going on.
+func criticalFunction() { // PAP
+    // Function is high risk and was comprehended by a human who is confident about its correctness and safety.
+}
+
+// This function performs critical operations X, Y, and Z.
+func criticalFunction() { // PHC
+    // Function is high risk and was comprehended by a human who is confident about its correctness and safety.
+}
+```

apiServer/apiServer.go

@@ -0,0 +1,100 @@
+package apiServer
+
+import (
+	"log/slog"
+	"net/http"
+
+	ouroboros "github.com/i5heu/ouroboros-db"
+	"github.com/i5heu/ouroboros-db/browserCrypt"
+)
+
+const (
+	defaultDataShards   = 4
+	defaultParityShards = 2
+)
+
+type Server struct {
+	mux       *http.ServeMux
+	db        *ouroboros.OuroborosDB
+	log       *slog.Logger
+	auth      AuthFunc
+	authStore browserCrypt.AuthStore
+}
+
+func New(db *ouroboros.OuroborosDB, opts ...Option) *Server { // A
+	s := &Server{
+		mux:  http.NewServeMux(),
+		db:   db,
+		log:  slog.Default(),
+		auth: defaultAuth,
+		authStore: browserCrypt.AuthStore{
+			OTK: make(map[string]browserCrypt.BrowserKey),
+		},
+	}
+
+	for _, opt := range opts {
+		opt(s)
+	}
+
+	s.routes()
+	return s
+}
+
+func (s *Server) routes() { // AC
+	s.mux.HandleFunc("POST /data", s.handleCreate)
+	s.mux.HandleFunc("GET /data/{key}", s.handleGet)
+	s.mux.HandleFunc("GET /data/{key}/children", s.handleChildren)
+	s.mux.HandleFunc("GET /data", s.handleList)
+	s.mux.HandleFunc("POST /data/bulk", s.handleBulkData)
+	s.mux.HandleFunc("GET /meta/threads", s.handleThreadSummaries)
+	s.mux.HandleFunc("GET /meta/thread/{key}/stream", s.handleThreadNodeStream)
+	s.mux.HandleFunc("GET /authProcess", s.handleAuthProcess)
+	s.mux.HandleFunc("POST /authProcess", s.handleAuthProcess)
+}
+
+func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) { // AC
+	origin := r.Header.Get("Origin")
+	if origin == "" {
+		origin = "*"
+	} else {
+		w.Header().Set("Vary", "Origin")
+	}
+
+	if origin != "" {
+		w.Header().Set("Access-Control-Allow-Origin", origin)
+	}
+
+	// Use explicit, fixed CORS header lists so preflight responses are cacheable
+	// and not dynamically varied by the incoming Access-Control-Request-Headers header.
+	// Keep headers aligned with what the client sends: Content-Type + Accept + our
+	// custom X-Auth headers and internal X-Ouroboros response/exposed headers.
+	allowedHeaders := "Content-Type, Accept, X-Auth-Token, X-Auth-Nonce, X-Auth-KeyHash-Base64"
+	w.Header().Set("Access-Control-Allow-Headers", allowedHeaders)
+	// Allow caching of preflight responses so repeated identical requests don't cause
+	// a preflight for every request. 86400s == 24 hours.
+	w.Header().Set("Access-Control-Max-Age", "86400")
+	w.Header().Set("Access-Control-Allow-Methods", "GET,POST,OPTIONS")
+	// If the API ever uses browser credentials (cookies) set to true. Current
+	// client uses custom headers, so credentials is not required; enable as false for now.
+	// If credentials are used, then Access-Control-Allow-Origin must not be '*'.
+	// w.Header().Set("Access-Control-Allow-Credentials", "true")
+	w.Header().Set(
+		"Access-Control-Expose-Headers",
+		"Content-Type, Content-Length, X-Ouroboros-Key, X-Ouroboros-Mime, X-Ouroboros-Is-Text, X-Ouroboros-Parent, X-Ouroboros-Children, X-Ouroboros-Created-At",
+	)
+
+	if r.Method == http.MethodOptions {
+		w.WriteHeader(http.StatusNoContent)
+		return
+	}
+
+	if r.URL.Path != "/authProcess" {
+		if err := s.auth(r, s.db); err != nil {
+			s.log.Warn("authentication failed", "error", err)
+			http.Error(w, http.StatusText(http.StatusUnauthorized), http.StatusUnauthorized)
+			return
+		}
+	}
+
+	s.mux.ServeHTTP(w, r)
+}