@mostajs/net 1.0.0-alpha.1 → 1.0.0

package/README.md

@@ -0,0 +1,197 @@
+# MostaNet
+
+> **Multi-protocol transport layer for @mostajs/orm** — expose your entities via 11+ protocols.
+> REST, GraphQL, WebSocket, SSE, JSON-RPC, MCP, and more.
+
+[![npm version](https://img.shields.io/npm/v/@mostajs/net.svg)](https://www.npmjs.com/package/@mostajs/net)
+[![license](https://img.shields.io/npm/l/@mostajs/net.svg)](LICENSE)
+
+---
+
+## What is MostaNet?
+
+MostaNet mirrors the **IDialect adapter pattern** of @mostajs/orm for the transport layer. Where ORM dialects abstract *where* data is stored (13 databases), transport adapters abstract *how* data is exposed (11+ protocols).
+
+```
+Client request → ITransport → OrmRequest → EntityService → IDialect → Database
+                                                ↓
+                              OrmResponse → ITransport → Client response
+```
+
+One `EntitySchema`, 13 databases, 11+ protocols = **143+ combinations**.
+
+---
+
+## Features
+
+- **6 transports implemented** — REST, GraphQL, WebSocket, SSE, JSON-RPC, MCP
+- **5 planned** — gRPC, tRPC, OData, NATS, Arrow Flight
+- **API Key management** — generate, revoke, validate with 3D permission matrix (key x SGBD x protocol)
+- **Middleware pipeline** — logging, auth, rate-limiting, CORS
+- **CLI** — `npx @mostajs/net serve` to start the server
+- **Fastify-based** — high-performance HTTP server
+- **MCP transport** — AI agents (Claude, GPT) can query any database via MCP protocol
+
+---
+
+## Quick Start
+
+```bash
+npm install @mostajs/orm @mostajs/net
+```
+
+### 1. Define schemas
+
+```typescript
+// schemas/user.ts
+import type { EntitySchema } from '@mostajs/orm'
+
+export const UserSchema: EntitySchema = {
+  name: 'User',
+  collection: 'users',
+  fields: {
+    name:  { type: 'string', required: true },
+    email: { type: 'string', required: true, unique: true },
+    role:  { type: 'string', default: 'user' },
+  },
+  relations: {},
+  indexes: [{ fields: { email: 'asc' }, unique: true }],
+  timestamps: true,
+}
+```
+
+### 2. Configure .env.local
+
+```bash
+# Database
+DB_DIALECT=postgres
+SGBD_URI=postgresql://user:pass@localhost:5432/mydb
+DB_SCHEMA_STRATEGY=update
+
+# Transports
+MOSTA_NET_REST_ENABLED=true
+MOSTA_NET_REST_PORT=3000
+MOSTA_NET_GRAPHQL_ENABLED=true
+MOSTA_NET_WS_ENABLED=true
+MOSTA_NET_SSE_ENABLED=true
+MOSTA_NET_JSONRPC_ENABLED=true
+MOSTA_NET_MCP_ENABLED=true
+
+# Logging (from @mostajs/orm)
+DB_SHOW_SQL=true
+DB_FORMAT_SQL=true
+DB_HIGHLIGHT_SQL=true
+DB_POOL_SIZE=20
+```
+
+### 3. Start the server
+
+```bash
+npx @mostajs/net serve
+```
+
+Or programmatically :
+
+```typescript
+import { startServer } from '@mostajs/net'
+
+await startServer({
+  schemas: [UserSchema],
+  port: 3000,
+})
+```
+
+### 4. Use it
+
+```bash
+# REST
+curl http://localhost:3000/api/v1/users
+curl -X POST http://localhost:3000/api/v1/users -d '{"name":"Dr Madani","email":"drmdh@msn.com"}'
+
+# GraphQL
+curl -X POST http://localhost:3000/graphql -d '{"query":"{ users { id name email } }"}'
+
+# JSON-RPC
+curl -X POST http://localhost:3000/rpc -d '{"jsonrpc":"2.0","method":"User.findAll","id":1}'
+
+# WebSocket
+wscat -c ws://localhost:3000/ws
+> {"op":"findAll","entity":"User"}
+
+# MCP (via Claude/GPT agent)
+# Tools: User_findAll, User_create, User_count, etc.
+```
+
+---
+
+## Transports
+
+| Transport | Protocol | Status | Use case |
+|-----------|----------|--------|----------|
+| **RestTransport** | HTTP REST | ✅ Production | Universal API (7 routes per entity) |
+| **GraphQLTransport** | GraphQL | ✅ Production | Flexible queries, auto-generated schema |
+| **WebSocketTransport** | WebSocket | ✅ Production | Bidirectional, real-time |
+| **SSETransport** | Server-Sent Events | ✅ Production | Real-time broadcast (entity.created/updated/deleted) |
+| **JsonRpcTransport** | JSON-RPC 2.0 | ✅ Production | Batch requests, method discovery |
+| **McpTransport** | Model Context Protocol | ✅ Production | AI agents (Claude, GPT, Copilot) |
+| GrpcTransport | gRPC | Planned | Service-to-service |
+| TrpcTransport | tRPC | Planned | End-to-end type safety |
+| ODataTransport | OData | Planned | Enterprise integration |
+| NatsTransport | NATS | Planned | Message queue |
+| ArrowFlightTransport | Arrow Flight | Planned | Analytics, big data |
+
+---
+
+## API Key Management
+
+```bash
+# Generate a key
+npx @mostajs/net generate-apikey "My App" live
+
+# List keys
+npx @mostajs/net list-keys
+
+# Revoke a key
+npx @mostajs/net revoke-key "My App"
+```
+
+Keys are stored in `.mosta/apikeys.json` with bcrypt hashes and a 3D permission matrix (API key x database x transport x operation).
+
+---
+
+## Architecture
+
+```
+@mostajs/net (this package)
+    ↓ depends on
+@mostajs/orm (13 databases)
+    ↓ managed by
+@mostajs/ornetadmin (admin UI)
+```
+
+- **net depends on orm** (unidirectional)
+- **orm has zero transport dependencies**
+- **ornetadmin writes config files** that orm and net read
+
+---
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `npx @mostajs/net serve` | Start the transport server |
+| `npx @mostajs/net info` | Show config, transports, API keys |
+| `npx @mostajs/net generate-apikey <name> [live\|test]` | Generate an API key |
+| `npx @mostajs/net list-keys` | List all API keys |
+| `npx @mostajs/net revoke-key <name>` | Revoke an API key |
+| `npx @mostajs/net hash-password <password>` | Hash a password (SHA-256) |
+
+---
+
+## License
+
+MIT — © 2025-2026 Dr Hamid MADANI <drmdh@msn.com>
+
+## Contributing
+
+Issues and PRs welcome at [github.com/apolocine/mosta-net](https://github.com/apolocine/mosta-net).

package/dist/server.js

@@ -31,8 +31,46 @@ export async function startServer() {
     const entityService = new EntityService(dialect);
     // 4. Get schemas
     const schemas = getAllSchemas();
-    // 5. Create shared Fastify instance
+    // 5. Display startup banner
+    const C = { reset: '\x1b[0m', dim: '\x1b[2m', cyan: '\x1b[36m', green: '\x1b[32m', yellow: '\x1b[33m', magenta: '\x1b[35m', gray: '\x1b[90m', blue: '\x1b[34m' };
+    const maskedUri = (process.env.SGBD_URI || '').replace(/:([^@]+)@/, ':***@');
+    console.log(`
+${C.cyan}┌─────────────────────────────────────────────────────┐${C.reset}
+${C.cyan}│${C.reset}  ${C.cyan}@mostajs/net${C.reset}                                        ${C.cyan}│${C.reset}
+${C.cyan}│${C.reset}  Dialect:    ${C.green}${process.env.DB_DIALECT || 'unknown'}${C.reset} ${C.dim}(${maskedUri})${C.reset}
+${C.cyan}│${C.reset}  Entities:   ${C.green}${schemas.map(s => s.name).join(', ')}${C.reset} ${C.dim}(${schemas.length})${C.reset}
+${C.cyan}│${C.reset}  Port:       ${C.yellow}${config.port}${C.reset}
+${C.cyan}│${C.reset}  Show SQL:   ${process.env.DB_SHOW_SQL === 'true' ? C.green + 'true' : C.gray + 'false'}${C.reset}  Format: ${process.env.DB_FORMAT_SQL === 'true' ? C.green + 'true' : C.gray + 'false'}${C.reset}  Highlight: ${process.env.DB_HIGHLIGHT_SQL === 'true' ? C.green + 'true' : C.gray + 'false'}${C.reset}
+${C.cyan}│${C.reset}  Pool:       ${C.yellow}${process.env.DB_POOL_SIZE || '10'}${C.reset}  Strategy: ${C.yellow}${process.env.DB_SCHEMA_STRATEGY || 'none'}${C.reset}
+${C.cyan}│${C.reset}  Transports: ${C.green}${getEnabledTransports(config).join(', ')}${C.reset} ${C.dim}(${getEnabledTransports(config).length})${C.reset}
+${C.cyan}└─────────────────────────────────────────────────────┘${C.reset}
+`);
+    // 5b. Create shared Fastify instance
     const app = Fastify({ logger: false });
+    // 5c. Request logger — log each transaction to terminal
+    app.addHook('onResponse', (req, reply, done) => {
+        const ms = reply.elapsedTime?.toFixed(0) || '?';
+        const status = reply.statusCode;
+        const method = req.method;
+        const url = req.url;
+        // Detect transport from URL
+        let transport = 'HTTP';
+        if (url.startsWith('/api/v1/'))
+            transport = 'REST';
+        else if (url.startsWith('/graphql'))
+            transport = 'GraphQL';
+        else if (url.startsWith('/rpc'))
+            transport = 'JSON-RPC';
+        else if (url.startsWith('/ws'))
+            transport = 'WS';
+        else if (url.startsWith('/events'))
+            transport = 'SSE';
+        else if (url.startsWith('/mcp'))
+            transport = 'MCP';
+        const statusColor = status < 300 ? C.green : status < 400 ? C.yellow : C.magenta;
+        console.log(`${C.dim}[NET:${C.cyan}${transport}${C.dim}]${C.reset} ${C.blue}${method}${C.reset} ${url} ${statusColor}${status}${C.reset} ${C.gray}(${ms}ms)${C.reset}`);
+        done();
+    });
     // 6. ORM handler (OrmRequest → EntityService → OrmResponse)
     const ormHandler = async (req, _ctx) => {
         return entityService.execute(req);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mostajs/net",
-  "version": "1.0.0-alpha.1",
+  "version": "1.0.0",
   "description": "Multi-protocol transport layer for @mostajs/orm — expose entities via REST, gRPC, GraphQL, WebSocket, SSE, tRPC, MCP, OData, Arrow Flight, JSON-RPC, NATS",
   "author": "Dr Hamid MADANI <drmdh@msn.com>",
   "license": "MIT",