geckos.io

Geckos.io provides a real-time communication layer. The server listens on a port and handles connections, while the client connects to the server to emit and listen for events.

Server Setup:

• Use geckos() to initialize the server.
• Call .listen(port) to start listening (default port is 9208).
• Use .onConnection(callback) to handle new client channels.
• Use io.room(roomId).emit(...) to broadcast to specific rooms.

Client Setup:

• Use geckos({ port }) to initialize the client.
• Use .onConnect(callback) to handle connection status.
• Use .on(event, callback) to listen for messages.
• Use .emit(event, data) to send messages.

// client.js
import geckos from '@geckos.io/client'

const channel = geckos({ port: 3000 })

channel.onConnect(error => {
  if (error) {
    console.error(error.message)
    return
  }

  channel.on('chat message', data => {
    console.log(`You got the message ${data}`)
  })

  channel.emit('chat message', 'a short message sent to the server')
})

// server.js
import geckos from '@geckos.io/server'

const io = geckos()

io.listen(3000)

io.onConnection(channel => {
  channel.onDisconnect(() => {
    console.log(`${channel.id} got disconnected`)
  })

  channel.on('chat message', data => {
    console.log(`got ${data} from "chat message"`)
    io.room(channel.roomId).emit('chat message', data)
  })
})

Geckos.io supports authentication via HTTP headers and server-side validation.

Client Side: Pass an authorization string in the geckos() configuration. This string is sent as an Authorization request header.

Server Side: Provide an authorization async function in the geckos() configuration.

• The function receives auth (the header string), the request, and the response.
• Return an object: This object will be attached to channel.userData on the client.
• Return true: Authorizes the connection without adding userData.
• Return false: Responds with a 401 Unauthorized error.
• Return a number: Responds with that specific HTTP status code (e.g., 400, 404).

Note: If the client and server are on different domains, you must set cors: { allowAuthorization: true } on the server.

// client.ts
const username = 'Yannick'
const password = '12E45'
const auth = `${username} ${password}`
const channel = geckos({ authorization: auth })

channel.onConnect(error => {
  if (error) {
    console.error('Status: ', error.status)
    return
  }
  console.log(channel.userData) // Access authenticated data
})

// server.ts
const io: GeckosServer = geckos({
  authorization: async (auth, request, response) => {
    const token = auth?.split(' ')
    const username = token?.[0]
    const password = token?.[1]

    const user = await database.getByName(username)

    if (user?.username === username && user?.password === password)
      return { username: user.username, level: user.level, points: user.points }

    return false
  },
  cors: { allowAuthorization: true }
})

You can run geckos.io as a standalone server or attach it to an existing Node.js HTTP or Express server. When attaching, ensure the client connects to the same port used by the HTTP server for signaling.

Standalone:

import geckos from '@geckos.io/server'
const io = geckos()
io.listen(3000)

Node.js HTTP Server:

import geckos from '@geckos.io/server'
import http from 'http'

const server = http.createServer()
const io = geckos()

io.addServer(server)
server.listen(3000)

Express:

import geckos from '@geckos.io/server'
import http from 'http'
import express from 'express'

const app = express()
const server = http.createServer(app)
const io = geckos()

io.addServer(server)
server.listen(3000)

// Express Example
import geckos from '@geckos.io/server'
import http from 'http'
import express from 'express'

const app = express()
const server = http.createServer(app)
const io = geckos()

io.addServer(server)
io.onConnection( channel => { ... })
server.listen(3000)