docs: add README.md
This commit is contained in:
Morten Olsen
40
.cursorrules
Normal file
40
.cursorrules
Normal file
@@ -0,0 +1,40 @@
|
|||||||
|
# Backbone MQTT Broker - AI Agent Documentation
|
||||||
|
|
||||||
|
## Project Overview
|
||||||
|
Kubernetes-native MQTT broker with JWT authentication and IAM-style access control. Built with TypeScript, Node.js, Fastify, Aedes MQTT broker, Kubernetes client, and Zod validation.
|
||||||
|
|
||||||
|
## Project Structure
|
||||||
|
- `src/access/` - JWT authentication and IAM-style authorization
|
||||||
|
- `src/api/` - HTTP API endpoints (Fastify)
|
||||||
|
- `src/config/` - Environment-based configuration
|
||||||
|
- `src/k8s/` - Kubernetes operator and CRD management
|
||||||
|
- `src/server/` - MQTT broker implementation (Aedes)
|
||||||
|
- `src/topics/` - Topic validation and rules
|
||||||
|
- `src/utils/` - Service container and shared utilities
|
||||||
|
|
||||||
|
## Code Style Rules
|
||||||
|
- Always use `.ts` file extensions in imports
|
||||||
|
- No default exports (use named exports only)
|
||||||
|
- Use `type` keyword for type definitions (not `interface`)
|
||||||
|
- Import order: builtin → external → internal → parent → sibling → index
|
||||||
|
- Add newlines between import groups
|
||||||
|
- Use path alias `#root/*` for absolute imports from `src/`
|
||||||
|
- Private class fields use `#` prefix (e.g., `#services`)
|
||||||
|
|
||||||
|
## TypeScript Configuration
|
||||||
|
- Module system: ESNext with NodeNext resolution
|
||||||
|
- Strict mode enabled
|
||||||
|
- Use `.ts` extensions in imports (allowImportingTsExtensions)
|
||||||
|
|
||||||
|
## Available Commands
|
||||||
|
- `pnpm dev` - Watch mode development
|
||||||
|
- `pnpm build` - TypeScript compilation
|
||||||
|
- `pnpm test` - Run all tests (lint + unit)
|
||||||
|
- `pnpm test:lint` - ESLint check
|
||||||
|
- `pnpm test:unit` - Vitest unit tests
|
||||||
|
|
||||||
|
## Key Patterns
|
||||||
|
- Dependency injection via `Services` container class
|
||||||
|
- Zod schemas for validation
|
||||||
|
- Environment variables via `Config` class
|
||||||
|
- Event-driven architecture for K8s resource watching
|
||||||
209
README.md
Normal file
209
README.md
Normal file
@@ -0,0 +1,209 @@
|
|||||||
|
# Backbone
|
||||||
|
|
||||||
|
A Kubernetes-native MQTT broker with fine-grained access control and topic validation.
|
||||||
|
|
||||||
|
## Features
|
||||||
|
|
||||||
|
- **MQTT 3.1.1/5.0 Broker** - Full-featured MQTT broker powered by Aedes
|
||||||
|
- **Kubernetes Integration** - Custom Resource Definitions (Client, Topic) for declarative configuration
|
||||||
|
- **JWT-based Authentication** - Pluggable authentication providers with JWT token support
|
||||||
|
- **Statement-based Authorization** - AWS IAM-style policy statements for fine-grained access control
|
||||||
|
- **Multiple Transport Protocols** - WebSocket and TCP support for flexible client connections
|
||||||
|
- **HTTP API** - RESTful API for broker management and monitoring
|
||||||
|
- **Topic Validation** - Configurable rules for topic structure and content validation
|
||||||
|
|
||||||
|
## Quick Start
|
||||||
|
|
||||||
|
### Using Docker Compose
|
||||||
|
|
||||||
|
1. Clone the repository and start the broker:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone <repository-url>
|
||||||
|
cd backbone
|
||||||
|
docker-compose up -d
|
||||||
|
```
|
||||||
|
|
||||||
|
2. The broker will be available on:
|
||||||
|
- **TCP MQTT**: `tcp://localhost:1883`
|
||||||
|
- **WebSocket MQTT**: `ws://localhost:8883/ws`
|
||||||
|
- **HTTP API**: `http://localhost:8883/api`
|
||||||
|
|
||||||
|
|
||||||
|
3. Connect with an MQTT client:
|
||||||
|
|
||||||
|
> [!IMPORTANT]
|
||||||
|
> Connecting requires credentials - documentation is still **TODO**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Using mosquitto_pub
|
||||||
|
mosquitto_pub -h localhost -p 1883 -t "test/topic" -m "Hello, Backbone!"
|
||||||
|
|
||||||
|
# Using mqtt.js (Node.js)
|
||||||
|
import mqtt from 'mqtt'
|
||||||
|
const client = mqtt.connect('ws://localhost:8883/ws')
|
||||||
|
```
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
Backbone can be configured using environment variables:
|
||||||
|
|
||||||
|
| Variable | Description | Default |
|
||||||
|
|----------|-------------|---------|
|
||||||
|
| `ADMIN_TOKEN` | Admin token for API requests | `undefined` |
|
||||||
|
| `TOKEN_SECRET` | JWT signing secret for authentication | `undefined` |
|
||||||
|
| `K8S_ENABLED` | Enable Kubernetes operator mode | `false` |
|
||||||
|
| `HTTP_ENABLED` | Enable HTTP/WebSocket server | `true` |
|
||||||
|
| `HTTP_PORT` | HTTP server port | `8883` |
|
||||||
|
| `TCP_ENABLED` | Enable TCP MQTT server | `true` |
|
||||||
|
| `TCP_PORT` | TCP server port | `1883` |
|
||||||
|
| `OIDC_ENABLED` | OIDC discovery URL | `undefined` |
|
||||||
|
| `OIDC_DISCOVERY` | OIDC discovery URL | `undefined` |
|
||||||
|
| `OIDC_CLIENT_ID` | OIDC client ID | `undefined` |
|
||||||
|
| `OIDC_CLIENT_SECRET` | OIDC client secret | `undefined` |
|
||||||
|
| `OIDC_CLIENT_SECRET` | OIDC client secret | `undefined` |
|
||||||
|
| `OIDC_GROUP_FIELD` | JWT field for reading groups | `groups` |
|
||||||
|
| `OIDC_ADMIN_GROUP` | JWT group for admins | `undefined` |
|
||||||
|
| `OIDC_WRITER_GROUP` | JWT group with publish access to queue | `undefined` |
|
||||||
|
| `OIDC_READER_GROUP` | JWT group with read-only access to queue | `undefined` |
|
||||||
|
|
||||||
|
### Example Configuration
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Basic configuration
|
||||||
|
export TOKEN_SECRET="your-secret-key"
|
||||||
|
export HTTP_ENABLED="true"
|
||||||
|
export TCP_ENABLED="true"
|
||||||
|
|
||||||
|
# Kubernetes mode
|
||||||
|
export K8S_ENABLED="true"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Kubernetes Integration
|
||||||
|
|
||||||
|
Backbone provides Kubernetes Custom Resource Definitions for declarative configuration:
|
||||||
|
|
||||||
|
### Client Resource
|
||||||
|
|
||||||
|
Define MQTT client access policies using the `Client` CRD:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
apiVersion: 'backbone.mortenolsen.pro/v1'
|
||||||
|
kind: Client
|
||||||
|
metadata:
|
||||||
|
name: sensor-client
|
||||||
|
namespace: production
|
||||||
|
spec:
|
||||||
|
statements:
|
||||||
|
- effect: allow
|
||||||
|
resources: ['sensors/**/data']
|
||||||
|
actions: ['mqtt:publish']
|
||||||
|
- effect: allow
|
||||||
|
resources: ['sensors/**/commands']
|
||||||
|
actions: ['mqtt:subscribe']
|
||||||
|
```
|
||||||
|
|
||||||
|
### Topic Resource
|
||||||
|
|
||||||
|
Configure topic validation rules:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
apiVersion: 'backbone.mortenolsen.pro/v1'
|
||||||
|
kind: Topic
|
||||||
|
metadata:
|
||||||
|
name: sensor-topics
|
||||||
|
namespace: production
|
||||||
|
spec:
|
||||||
|
patterns:
|
||||||
|
- pattern: 'sensors/**/data'
|
||||||
|
maxMessageSize: 1024
|
||||||
|
allowedQoS: [0, 1]
|
||||||
|
```
|
||||||
|
|
||||||
|
The Kubernetes operator automatically watches these resources and applies the access policies and validation rules to the MQTT broker.
|
||||||
|
|
||||||
|
## Authentication & Authorization
|
||||||
|
|
||||||
|
### Authorization Statements
|
||||||
|
|
||||||
|
Access control is defined using statement-based policies similar to AWS IAM:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
statements:
|
||||||
|
- effect: allow # or "deny"
|
||||||
|
resources: ['*'] # MQTT topic patterns
|
||||||
|
actions: ['*'] # MQTT actions
|
||||||
|
```
|
||||||
|
|
||||||
|
#### MQTT Actions
|
||||||
|
|
||||||
|
- `mqtt:publish` - Permission to publish messages to topics
|
||||||
|
- `mqtt:subscribe` - Permission to subscribe to topics
|
||||||
|
- `mqtt:read` - Permission to receive messages from topics
|
||||||
|
|
||||||
|
#### Resource Patterns
|
||||||
|
|
||||||
|
- `*` - All topics
|
||||||
|
- `sensors/*` - All topics under sensors/
|
||||||
|
- `sensors/+/data` - Topics matching the pattern (single-level wildcard)
|
||||||
|
- `sensors/#` - All topics under sensors/ (multi-level wildcard)
|
||||||
|
|
||||||
|
## API
|
||||||
|
|
||||||
|
### Endpoints
|
||||||
|
|
||||||
|
- **WebSocket MQTT**: `ws://host:8883/ws`
|
||||||
|
- **TCP MQTT**: `tcp://host:1883`
|
||||||
|
- **HTTP API**: `http://host:8883/api/*`
|
||||||
|
|
||||||
|
### HTTP API
|
||||||
|
|
||||||
|
The HTTP API provides management endpoints for:
|
||||||
|
- Client management
|
||||||
|
- Topic configuration
|
||||||
|
- Broker statistics
|
||||||
|
- Health checks
|
||||||
|
|
||||||
|
## Development
|
||||||
|
|
||||||
|
### Prerequisites
|
||||||
|
|
||||||
|
- Node.js 23 or higher
|
||||||
|
- pnpm package manager
|
||||||
|
|
||||||
|
### Installation
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Install dependencies
|
||||||
|
pnpm install
|
||||||
|
|
||||||
|
# Start development server
|
||||||
|
pnpm dev
|
||||||
|
|
||||||
|
# Build for production
|
||||||
|
pnpm build
|
||||||
|
|
||||||
|
# Run tests
|
||||||
|
pnpm test
|
||||||
|
```
|
||||||
|
|
||||||
|
### Project Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
src/
|
||||||
|
├── access/ # Authentication and authorization
|
||||||
|
├── api/ # HTTP API endpoints
|
||||||
|
├── config/ # Configuration management
|
||||||
|
├── k8s/ # Kubernetes operator and CRDs
|
||||||
|
├── server/ # MQTT broker implementation
|
||||||
|
├── topics/ # Topic validation rules
|
||||||
|
└── utils/ # Shared utilities and services
|
||||||
|
```
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
This project is licensed under the GNU General Public License v3.0 (GPL-3.0).
|
||||||
|
|
||||||
|
## Author
|
||||||
|
|
||||||
|
Created by [@morten-olsen](https://github.com/morten-olsen)
|
||||||
Reference in New Issue
Block a user