René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Extract Minimal Viable LWS Server","articleBody":"## Summary\n\nCreate a minimal, standalone LWS (Linked Web Storage) server extracted from JSS that implements **only** the core W3C LWS protocol without Solid-specific or extended features.\n\n**Goal:** Reference implementation and minimal server for LWS protocol testing, embedding, and education.\n\n**Related:**\n- Issue #87 - LWS Protocol Mode (infrastructure foundation)\n- PR #88 - LWS Mode Implementation (draft)\n- [W3C LWS Protocol PR #37](https://github.com/w3c/lws-protocol/pull/37) - Initial CRUD spec\n- [W3C LWS Protocol Repository](https://github.com/w3c/lws-protocol)\n\n## Motivation\n\nJSS has grown to support many protocols and features:\n- Solid Protocol (LDP-based CRUD)\n- Solid-OIDC (DPoP, dynamic registration, RS256/ES256)\n- Passkey authentication (WebAuthn/FIDO2)\n- WebID-TLS client certificates\n- Nostr authentication (NIP-98)\n- ActivityPub federation\n- Nostr relay (NIP-01)\n- Git HTTP backend\n- Mashlib data browser\n- WebSocket notifications\n- Storage quotas\n- N3 Patch, SPARQL Update\n- Content negotiation (Turtle ↔ JSON-LD)\n\n**Problem:** This makes JSS heavy for users who just want simple Linked Data storage following LWS spec.\n\n**Solution:** Extract a minimal LWS server (~500-1000 LOC) that focuses solely on the core protocol.\n\n## Use Cases\n\n1. **Reference Implementation** - Demonstrate LWS spec compliance\n2. **Client Testing** - Lightweight server for testing LWS clients\n3. **Embedding** - Drop into other Node.js apps as a module\n4. **Education** - Learn LWS protocol without distractions\n5. **Microservices** - Lightweight storage layer for service architectures\n6. **Development** - Fast startup, minimal dependencies\n\n## Scope: What to Include\n\n### Core LWS Protocol (Minimal)\n\n- ✅ **GET** - Read resources and containers\n- ✅ **HEAD** - Resource metadata\n- ✅ **POST** - Create resources with Slug header\n- ✅ **PUT** - Create or update resources\n- ✅ **DELETE** - Remove resources\n- ✅ **OPTIONS** - CORS preflight\n- ✅ **ETags** - Concurrency control (If-Match, If-None-Match)\n- ✅ **Link headers** - Resource types, container metadata\n- ✅ **CORS** - Cross-origin support\n- ✅ **File-based storage** - Simple filesystem backend\n\n### Optional (Phase 2)\n\n- ⚠️ **PATCH** - Simple JSON Merge Patch (RFC 7386) only\n- ⚠️ **Linkset endpoints** - Metadata via `/resource;linkset` (when LWS spec defines it)\n- ⚠️ **Basic auth** - Simple token-based authentication\n- ⚠️ **Multi-user** - Optional pod isolation\n\n## Scope: What to EXCLUDE\n\nAll Solid-specific and extended features:\n\n- ❌ Solid-OIDC (full IdP/DPoP implementation)\n- ❌ Passkey authentication\n- ❌ WebID-TLS\n- ❌ Nostr authentication/relay\n- ❌ ActivityPub federation\n- ❌ Git HTTP backend\n- ❌ Mashlib data browser\n- ❌ WebSocket notifications\n- ❌ N3 Patch\n- ❌ SPARQL Update\n- ❌ Content negotiation (Turtle ↔ JSON-LD)\n- ❌ Storage quotas\n- ❌ Invite-only registration\n- ❌ WAC (Web Access Control)\n- ❌ WebID profiles\n- ❌ Complex IdP interactions\n\n## Proposed Architecture\n\n### File Structure\n\n\\`\\`\\`\nlws-server/\n├── package.json\n├── README.md\n├── index.js              # Main entry point\n├── lib/\n│   ├── server.js         # Fastify setup\n│   ├── handlers/\n│   │   ├── get.js       # GET/HEAD\n│   │   ├── put.js       # PUT\n│   │   ├── post.js      # POST\n│   │   ├── delete.js    # DELETE\n│   │   └── options.js   # OPTIONS\n│   ├── storage.js        # Filesystem operations\n│   ├── headers.js        # Link/ETag headers\n│   └── auth.js           # Simple token auth (optional)\n└── test/\n    └── lws.test.js\n\\`\\`\\`\n\n### Size Target\n\n- **~500-1000 LOC** (vs JSS's ~8000+ LOC)\n- **~5-10 dependencies** (vs JSS's 22)\n- **Single file option** - Could bundle to single ESM file for embedding\n\n### Dependencies (Minimal)\n\n\\`\\`\\`json\n{\n  \"dependencies\": {\n    \"fastify\": \"^5.x\",\n    \"@fastify/cors\": \"^10.x\",\n    \"fs-extra\": \"^11.x\"\n  },\n  \"devDependencies\": {\n    \"node:test\": \"builtin\"\n  }\n}\n\\`\\`\\`\n\n## API Example\n\n### Programmatic Use\n\n\\`\\`\\`javascript\nimport { createLWSServer } from 'lws-server';\n\nconst server = createLWSServer({\n  port: 3000,\n  root: './data',\n  cors: true,\n  auth: false  // Optional token-based auth\n});\n\nawait server.listen();\nconsole.log('LWS server running on http://localhost:3000');\n\\`\\`\\`\n\n### CLI Use\n\n\\`\\`\\`bash\nnpm install -g lws-server\n\nlws-server --port 3000 --root ./data\n\\`\\`\\`\n\n### Single-User Mode (Default)\n\n\\`\\`\\`bash\n# Creates flat structure (no /alice/ containers)\nPUT /data.json          # Creates /data.json\nPOST / + Slug=file      # Creates /file.json\nGET /                   # Lists all resources\n\\`\\`\\`\n\n### Multi-User Mode (Optional)\n\n\\`\\`\\`bash\nlws-server --multiuser\n\nPUT /alice/data.json    # Creates /alice/data.json\nPUT /bob/data.json      # Creates /bob/data.json\n\\`\\`\\`\n\n## Extraction Strategy\n\n### Option 1: Fork and Strip Down\n\n1. Fork JSS to new repo: \\`lws-server\\`\n2. Remove all non-LWS features\n3. Simplify handlers\n4. Remove dependencies\n5. Refactor to minimal core\n\n**Pros:**\n- Reuse existing, tested code\n- Keep git history for core features\n- Faster initial development\n\n**Cons:**\n- May carry technical debt\n- Harder to achieve size target\n\n### Option 2: Clean Room Implementation\n\n1. Create new repo from scratch\n2. Reference JSS handlers for logic\n3. Implement only LWS core\n4. Modern ESM-first design\n\n**Pros:**\n- Clean codebase\n- Easier to hit size target\n- No legacy patterns\n\n**Cons:**\n- More initial work\n- Need to retest everything\n\n### Recommendation: Option 1 (Fork and Strip)\n\nStart with JSS handlers, progressively remove features until minimal.\n\n## Implementation Plan\n\n### Phase 1: Core Extraction (~4-8 hours)\n\n- [ ] Create \\`lws-server\\` repo\n- [ ] Extract core handlers (GET, PUT, POST, DELETE, OPTIONS)\n- [ ] Extract filesystem storage module\n- [ ] Extract header generation (Link, ETag, CORS)\n- [ ] Remove all Solid-specific code\n- [ ] Remove all extended features (IdP, passkeys, etc.)\n- [ ] Simplify server setup\n\n### Phase 2: Polish (~2-4 hours)\n\n- [ ] Add CLI interface\n- [ ] Add programmatic API\n- [ ] Write minimal README\n- [ ] Add basic tests\n- [ ] Publish to npm as \\`lws-server\\`\n\n### Phase 3: Documentation (~1-2 hours)\n\n- [ ] API documentation\n- [ ] LWS compliance notes\n- [ ] Migration guide from JSS\n- [ ] Embedding examples\n\n## Success Metrics\n\n**Size:**\n- ✅ \u003c 1000 LOC\n- ✅ \u003c 10 dependencies\n- ✅ \u003c 5MB node_modules\n\n**Performance:**\n- ✅ \u003c 100ms startup time\n- ✅ \u003c 5ms per request (simple GET)\n- ✅ \u003c 50MB memory footprint\n\n**Usability:**\n- ✅ Single command to start\n- ✅ Zero config for basic use\n- ✅ Embeddable in Node.js apps\n\n## Comparison Table\n\n| Feature | JSS | lws-server |\n|---------|-----|------------|\n| **LOC** | ~8000+ | ~500-1000 |\n| **Dependencies** | 22 | ~5-10 |\n| **Startup** | ~500ms | \u003c100ms |\n| **Memory** | ~150MB | \u003c50MB |\n| **Protocols** | LDP, LWS, OIDC, AP, Nostr, Git | LWS only |\n| **Auth** | 5 methods | Simple token |\n| **Features** | 20+ | 5 core CRUD |\n\n## Package Name Options\n\n- \\`lws-server\\` ✅ (recommended)\n- \\`minimal-lws\\`\n- \\`lws-storage\\`\n- \\`simple-lws\\`\n- \\`lws-core\\`\n\n## Relationship to Existing Work\n\nThis builds on:\n- **Issue #87** - LWS Protocol Mode analysis and decision criteria\n- **PR #88** - LWS mode infrastructure (config flag, request decoration)\n\n**Differences:**\n- #87/#88: Add LWS support **to JSS** (alongside Solid features)\n- This issue: Extract **separate minimal server** (LWS only, no Solid)\n\n**Use together:**\n- JSS \\`--lws-mode\\` for production multi-protocol server\n- \\`lws-server\\` for embedding, testing, education\n\n## Questions to Resolve\n\n1. **Repository location**: New org or under JavaScriptSolidServer?\n2. **npm scope**: Publish as \\`lws-server\\` or \\`@lwsprotocol/server\\`?\n3. **Versioning**: Start at 1.0.0 or 0.1.0?\n4. **License**: MIT (same as JSS)?\n5. **Auth model**: Include simple token auth or be completely auth-free?\n6. **Timing**: Wait for LWS spec to mature or start now as reference?\n\n---\n\n**Priority:** Low-Medium - Useful for ecosystem, not urgent\n**Effort:** 1-2 days for functional MVP\n**Dependencies:** None (can start anytime, spec still evolving)\n**Status:** Awaiting LWS ecosystem signals (per #87 decision criteria)","author":{"url":"https://github.com/melvincarvalho","@type":"Person","name":"melvincarvalho"},"datePublished":"2026-01-14T15:12:54.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":0},"url":"https://github.com/89/JavaScriptSolidServer/issues/89"}