@outray/core

@outray/core

Core tunnel client for Outray - shared between the CLI and framework plugins.

This package provides the low-level WebSocket client for establishing tunnels to the Outray server. It's used internally by:

• outray (CLI)
• @outray/vite (Vite plugin)
• Other framework integrations

Installation

npm install @outray/core
# or
pnpm add @outray/core
# or
yarn add @outray/core

Usage

import { OutrayClient } from '@outray/core';

const client = new OutrayClient({
  localPort: 3000,
  
  // Optional: API key for authentication
  apiKey: process.env.OUTRAY_API_KEY,
  
  // Optional: Request a specific subdomain
  subdomain: 'my-app',
  
  // Callbacks
  onTunnelReady: (url) => {
    console.log(`Tunnel ready at: ${url}`);
  },
  
  onError: (error, code) => {
    console.error(`Error: ${error.message}`);
  },
  
  onRequest: (info) => {
    console.log(`${info.method} ${info.path} - ${info.statusCode} (${info.duration}ms)`);
  },
  
  onReconnecting: (attempt, delay) => {
    console.log(`Reconnecting in ${delay}ms (attempt ${attempt})`);
  },
});

// Start the tunnel
client.start();

// Check status
console.log('Connected:', client.isConnected());
console.log('URL:', client.getUrl());

// Stop when done
client.stop();

API

OutrayClient

Constructor Options

Option	Type	Default	Description
localPort	number	required	Local port to proxy requests to
serverUrl	string	'wss://api.outray.dev/'	Outray server WebSocket URL
apiKey	string	-	API key for authentication
subdomain	string	-	Subdomain to use (requires auth)
customDomain	string	-	Custom domain (must be configured in dashboard)
protocol	'http' | 'tcp' | 'udp'	'http'	Tunnel protocol type
remotePort	number	-	Remote port for TCP/UDP tunnels
onTunnelReady	(url: string, port?: number) => void	-	Called when tunnel is established
onError	(error: Error, code?: string) => void	-	Called on error
onClose	(reason?: string) => void	-	Called when tunnel closes
onReconnecting	(attempt: number, delay: number) => void	-	Called before reconnect
onRequest	(info: RequestInfo) => void	-	Called for each proxied request

Methods

Method	Returns	Description
start()	void	Start the tunnel connection
stop()	void	Stop the tunnel and cleanup
getUrl()	string | null	Get the assigned tunnel URL
isConnected()	boolean	Check if currently connected

Protocol Utilities

import { encodeMessage, decodeMessage } from '@outray/core';

// Encode a message to send
const encoded = encodeMessage({ type: 'open_tunnel', apiKey: '...' });

// Decode a received message
const message = decodeMessage(rawData);

Error Codes

import { ErrorCodes } from '@outray/core';

// Available error codes:
ErrorCodes.SUBDOMAIN_IN_USE
ErrorCodes.AUTH_FAILED
ErrorCodes.LIMIT_EXCEEDED
ErrorCodes.INVALID_SUBDOMAIN
ErrorCodes.CUSTOM_DOMAIN_NOT_CONFIGURED

Building Framework Plugins

If you're building a framework plugin, use @outray/core as the foundation:

import { OutrayClient, type OutrayClientOptions } from '@outray/core';

export function myFrameworkPlugin(options: MyPluginOptions) {
  let client: OutrayClient | null = null;
  
  return {
    onServerStart(port: number) {
      client = new OutrayClient({
        localPort: port,
        apiKey: options.apiKey,
        onTunnelReady: (url) => {
          // Display URL in framework's style
        },
        onError: (error) => {
          // Handle errors appropriately
        },
      });
      
      client.start();
    },
    
    onServerStop() {
      client?.stop();
    },
  };
}

License

MIT © akinloluwami