What is Gluer?

Gluer is a real-time communication platform that unifies WebSockets and REST APIs into a single, intelligent message bus. It enables front-ends and back-ends to communicate simply and efficiently through a centralized server.

Architecture

┌─────────────┐         ┌─────────────┐         ┌─────────────┐
│   Frontend  │◄───────►│   Gluer     │◄───────►│   Backend   │
│  (gluer-js) │         │   Server    │         │(gluer-nodejs│
└─────────────┘         └─────────────┘         └─────────────┘

1. Create an Account

Visit https://gluer.io and click "Get Started" or "Register".

Step 1: Fill out the form with your name, email, and password.

Name: Your full name
Email: Your email (used for login)
Password: A secure password
Password Confirmation: Confirm your password

2. Create a Project

After logging in, you will be redirected to the dashboard. Click "New Project" and provide a name for your project.

Important: Each project automatically generates a Public Key and a Private Key.

Project Keys

Public Key: Used by frontend (gluer-js)
Private Key: Used by backend (gluer-nodejs)
Password: Additional password for authentication

You can view all your keys in the dashboard at https://gluer.io/ctx

3. Using gluer-js (Frontend)

Installation

Via npm:

npm install gluer-js

Or via CDN:

<script src="https://unpkg.com/gluer-js/dist/gluer-js.umd.js"></script>

Basic Setup

import gluer from 'gluer-js';

// Configure with your project ID (Public Key)
gluer.setup({
  url: 'wss://ws.gluer.io',        // Gluer server (optional)
  project: 'YOUR_PUBLIC_KEY',       // Your project's Public Key
  sessionId: 'your-unique-session'  // Session ID (optional)
});

// Connect to server
gluer.connect();

Connection Events

// When connected
gluer.addEventListener('connection', (e) => {
  console.log('Connected!', e.detail);
});

// When disconnected
gluer.addEventListener('disconnect', () => {
  console.log('Disconnected');
});

// When an error occurs
gluer.addEventListener('error', (e) => {
  console.error('Error:', e.detail);
});

Sending Messages

// Asynchronous (no response)
gluer.sendMsg('command_name', { key1: 'value1' });

// Synchronous (with response)
try {
  const response = await gluer.sendMsgSync('command_name', { key1: 'value1' });
  console.log('Response:', response.data);
} catch (error) {
  console.error('Error:', error.message);
}

// Via HTTP
const response = await gluer.sendHttp('command_name', { key1: 'value1' });

Subscribing to Channels

// Subscribe to a channel
gluer.subscribe('channel_name', (message) => {
  console.log('New message:', message);
});

// Or for multiple channels
gluer.subscribe(['channel1', 'channel2'], (message) => {
  console.log('Message from channel:', message);
});

Context Data (Important!)

The setContextItem method allows you to set values that are automatically sent with every subsequent message. This is especially useful for passing session IDs, user authentication tokens, or any data that needs to be available on every request.

Common Use Case: Store the session ID after user login. The session will be automatically included in all backend calls without needing to pass it manually each time.

// After user login, store the session ID
gluer.setContextItem("session", userSessionId);

// Now every message automatically includes the session
// You don't need to pass it manually in each call
gluer.sendMsg('orders:list', {}); 
// Backend receives: { session: "abc123", ... }

// Another example: store user info
gluer.setContextItem("user_id", "user-456");
gluer.setContextItem("role", "admin");

// Remove context when user logs out
gluer.deleteContextItem("session");
gluer.deleteContextItem("user_id");
gluer.deleteContextItem("role");

API Reference

Method	Description
setup(config)	Configure the library
connect()	Connect to WebSocket server
disconnect()	Disconnect from server
send(payload)	Send message without waiting for response
sendMsg(cmd, data)	Send asynchronous message
sendMsgSync(cmd, data, timeout)	Send message and wait for response
sendHttp(cmd, data)	Send HTTP request
subscribe(channels, callback)	Subscribe to channel(s)
setContextItem(key, value)	Add context data
deleteContextItem(key)	Remove context data

4. Using gluer-nodejs (Backend)

Installation

npm install gluer-nodejs

Basic Setup

import * as gluer from 'gluer-nodejs';

// Connect to server with your Private Key
gluer.connect('YOUR_PRIVATE_KEY');

Registering Functions (Plugins)

// Register a function
async function helloWorld(data) {
  console.log('Received data:', data);
  return { message: 'Hello from backend!' };
}

gluer.register_plugin('my_plugin', 'helloWorld', helloWorld);

// Or register an entire object
const myService = {
  async calculate(data) {
    return { result: data.a + data.b };
  },
  
  async getUser(data) {
    return { name: 'John', email: '[email protected]' };
  }
};

gluer.register_object('my_service', myService);

Interceptors

gluer.register_interceptor('my_plugin', async (data, header) => {
  // Validate token
  if (!data.token) {
    throw new Error('Token required');
  }
  
  // Return true to allow
  // Return false to block
  // Return modified data to alter the request
  return true;
});

Registering Directory

// Create files with the pattern: name_plugin_plugin.js
// Example: user_plugin.js

// File contents:
export const plugin = 'user';

export async function get(data) {
  return { users: [...] };
}

export async function create(data) {
  return { id: 1, ...data };
}

// Then register the directory:
gluer.register_directory('./plugins');

API Reference

Method	Description
connect(project_id)	Connect to server with project ID
set_websocket_url(url)	Set custom WebSocket URL
register_plugin(plugin, name, fn)	Register a function
register_object(plugin, obj)	Register an object as plugin
register_directory(dir)	Register all plugins from a directory
register_interceptor(plugin, fn)	Add interceptor
clear_interceptor(plugin)	Remove interceptor
get_interceptor(plugin)	Get interceptor

5. Full Example

Backend (server.js)

import * as gluer from 'gluer-nodejs';

// Connect to Gluer
gluer.connect('YOUR_PRIVATE_KEY');

// Register functions
async function add(data) {
  return { result: data.a + data.b };
}

async function multiply(data) {
  return { result: data.a * data.b };
}

gluer.register_plugin('calculator', 'add', add);
gluer.register_plugin('calculator', 'multiply', multiply);

console.log('Backend connected to Gluer!');

Frontend (app.js)

import gluer from 'gluer-js';

// Configure
gluer.setup({
  project: 'YOUR_PUBLIC_KEY'
});

gluer.connect();

// Call backend function
async function test() {
  const sum = await gluer.sendMsgSync('calculator:add', { a: 5, b: 3 });
  console.log('5 + 3 =', sum.data.result); // 8
  
  const mult = await gluer.sendMsgSync('calculator:multiply', { a: 4, b: 7 });
  console.log('4 * 7 =', mult.data.result); // 28
}

test();

Limits & Usage

Free Plan: 1 million requests per month
Keys: Public Key (frontend) and Private Key (backend)
Active Servers: Real-time monitoring

You can view your projects and keys in the dashboard at https://gluer.io/ctx