TelePortal

TelePortal: A storage, transport & runtime agnostic Y.js server/provider. Built on web primitives, supports subdocs, and handles everything without in-memory storage. Perfect for collaborative apps! 🚀

This is a Y.js Server & Provider that aims to be storage, transport, and runtime agnostic.

• undefined💾 Storage: Storage is completely de-coupled from the library, you can store documents in a KV, relational database or even S3, totally up to you

  • Currently this is implemented with unstorage which can swap out drivers for many different storage schemes.

• undefined🔄 Transport: everything is defined using Web standard streams and encodes to a Uint8Array

  • Use Websockets, HTTP, HTTP + SSE, anything you like that can fulfill a bidirectional communication

• undefined🏃 Runtime: built on web primitives, everything should work on any JavaScript runtime, with minimal dependencies

Features

Core Features

• undefined🌏 Ease-of-use: We won’t make you learn what a Y.Doc is, and make you store it somewhere, keep an instance of the provider, and you’ll have everything you need!

• undefined📁 Sub-docs: Full support for Y.js subdocs - there aren’t many providers out there which have implemented this, this one does 😉

• undefined🏎️ Performance: Built on top of web-native Streams APIs, supporting control-flow, backpressure. All without actually storing the documents in-memory

• undefined🔄 Zero in-memory storage: Documents are never stored in memory on the server, making it perfect for scalable deployments

Protocol & Synchronization

• undefinedBinary Protocol: Efficient binary protocol with magic number validation and version checking
• undefinedDocument Sync: Full Y.js synchronization with sync-step-1, sync-step-2, updates, and sync-done messages
• undefinedAwareness: Real-time user presence, cursor positions, and selection states
• undefinedMessage Batching: Multiple messages can be batched into a single transmission for efficiency
• undefinedPing/Pong: Built-in keep-alive messages for connection health monitoring

File Transfer

• undefinedChunked File Transfer: Files are split into 64KB chunks for efficient transfer
• undefinedMerkle Tree Verification: Content-addressable storage with Merkle tree integrity verification
• undefinedLarge File Support: Files up to 1GB supported
• undefinedEncrypted Files: Optional end-to-end encryption for file transfers
• undefinedIncremental Uploads: Support for resumable uploads from temporary storage

Milestones (Document Snapshots)

• undefinedCreate Snapshots: Capture document state at any point in time
• undefinedList Milestones: Query all milestones for a document
• undefinedLazy Loading: Request milestone snapshots on-demand
• undefinedNamed Milestones: Optional naming for milestones with update support
• undefinedMetadata Management: Track milestone creation times and document associations

Storage

• undefinedStorage Agnostic: Interface-based design - implement for any storage backend
• undefinedMultiple Implementations:undefined
  • undefinedUnstorage: Works with Redis, PostgreSQL, MySQL, SQLite, S3, Cloudflare R2, Azure Blob, and more
  • undefinedIn-Memory: Fast in-memory storage for testing and development
  • undefinedEncrypted/Unencrypted: Support for both encrypted and unencrypted document storage
• undefinedSeparate Storage Types:undefined
  • Document storage (Y.js updates and metadata)
  • File storage (chunked files with Merkle trees)
  • Milestone storage (document snapshots)
  • Temporary upload storage (upload sessions)

Transport & Connections

• undefinedWebSocket: Full WebSocket support with automatic reconnection
• undefinedHTTP: HTTP-based transport for environments where WebSockets aren’t available
• undefinedServer-Sent Events (SSE): SSE support for one-way server-to-client communication
• undefinedFallback Connection: Automatic fallback between WebSocket, HTTP, and SSE
• undefinedMessage Buffering: Automatic message buffering when disconnected
• undefinedConnection State Management: Track connection state (connected, disconnected, connecting, errored)
• undefinedIn-Flight Message Tracking: Monitor messages in transit

End-to-End Encryption (E2EE)

• undefinedAES-GCM Encryption: Industry-standard encryption for document updates
• undefinedEncrypted Transport: Optional encryption layer for all document messages
• undefinedKey Management: Utilities for creating, importing, and exporting encryption keys
• undefinedEncrypted File Support: Files can be encrypted before chunking and transfer
• undefinedLamport Clock: Vector clocks for encrypted message ordering

Security & Authentication

• undefinedJWT Token Authentication: Built-in JWT token support using jose library
• undefinedIAM-like Permissions: Granular permission system with document pattern matching
• undefinedPermission Types: read, write per message
• undefinedPattern Matching: Support for exact, prefix, wildcard, and suffix patterns
• undefinedRoom-based Access Control: Multi-tenant support with room/organization isolation
• undefinedDocument Access Builder: Fluent API for constructing complex permission rules
• undefinedToken Expiration: Configurable token expiration and validation

Monitoring & Observability

• undefinedPrometheus Metrics: Built-in Prometheus metrics collection
• undefinedHealth Checks: Health status endpoints with component checks
• undefinedStatus Endpoints: Real-time server status (clients, sessions, messages)
• undefinedMetrics Collected:undefined
  • Active clients and sessions
  • Total documents opened
  • Message counts by type
  • Message processing duration
  • Storage operation counts and duration
  • Error counts by type
• undefinedUptime Tracking: Server uptime monitoring

Developer Experience

• undefinedDevTools Integration: Built-in DevTools for debugging and monitoring
• undefinedAgent Functionality: Server-side document manipulation with Agent API
• undefinedTypeScript Support: Full TypeScript support with comprehensive type definitions
• undefinedComprehensive Logging: Structured logging with @logtape/logtape
• undefinedHTTP Server Handlers: Ready-to-use HTTP handlers for integration
• undefinedWebSocket Server Handlers: Pre-built WebSocket upgrade and connection handlers

Provider Features

• undefinedAutomatic Reconnection: Smart reconnection logic with exponential backoff
• undefinedOffline Persistence: IndexedDB persistence for offline support
• undefinedSubdoc Support: Full Y.js subdoc synchronization
• undefinedConnection Sharing: Share connections across multiple providers
• undefinedObservable Events: Event-driven architecture with observable patterns

Transport Middleware

• undefinedRedis Transport: Redis-based pub/sub for distributed deployments
• undefinedNATS Transport: NATS integration for message queuing
• undefinedRate Limiting: Built-in rate limiting support
• undefinedMessage Validation: Message validation middleware
• undefinedACK Support: Acknowledgment support for reliable message delivery
• undefinedPubSub Support: Publish/subscribe patterns for multi-server deployments
• undefinedLogger Transport: Logging middleware for debugging

Examples & Integrations

• undefinedExcalidraw Example: Complete example integration with Excalidraw
• undefinedPlayground: Interactive playground for testing and development
• undefinedMultiple Server Implementations: Examples for Bun, Node.js, and more

Quick Start

import { Server } from "teleportal/server";
import { createInMemory } from "teleportal/storage";
import { getWebsocketHandlers } from "teleportal/websocket-server";

const server = new Server({
  getStorage: async (ctx) => {
    const { documentStorage } = createInMemory();
    return documentStorage;
  },
});

const handlers = getWebsocketHandlers({
  onConnect: async ({ transport, context, id }) => {
    await server.createClient(transport, context, id);
  },
  onDisconnect: async (id) => {
    await server.disconnectClient(id);
  },
});

Installation

npm install teleportal
# or
bun add teleportal
# or
pnpm add teleportal

Documentation

• Protocol Documentation - Complete protocol specification
• Storage Documentation - Storage interface and implementations
• Provider Documentation - Provider and connection architecture
• Token Documentation - JWT authentication and permissions

Exports

TelePortal provides multiple entry points:

• teleportal - Core library
• teleportal/server - Server implementation
• teleportal/providers - Client providers
• teleportal/storage - Storage interfaces and implementations
• teleportal/http - HTTP handlers
• teleportal/websocket-server - WebSocket server handlers
• teleportal/protocol - Protocol encoding/decoding
• teleportal/protocol/encryption - Encryption protocol
• teleportal/transports - Transport middleware
• teleportal/transports/redis - Redis transport
• teleportal/transports/nats - NATS transport
• teleportal/token - JWT token utilities
• teleportal/encryption-key - Encryption key management
• teleportal/monitoring - Metrics and monitoring
• teleportal/devtools - DevTools integration
• teleportal/merkle-tree - Merkle tree utilities

Requirements

• Node.js >= 24
• Modern JavaScript runtime (Node.js, Bun, Deno, etc.)

License

MPL-2.0

[!NOTE]
🚧 This is still a work in progress. Feedback and contributions are welcome!