fostrom 0.0.1

package/config.js

@@ -0,0 +1,115 @@
+/* DEVICE CONFIG */
+
+const id_regex = RegExp(/[^a-zA-Z0-9]/)
+const device_secret_regex = RegExp(/FOS-[^a-zA-Z0-9]/)
+
+/* Callbacks */
+const on_connect = () => console.log('[Fostrom] Connected')
+const on_disconnect = () => console.log('[Fostrom] Disconnected')
+
+const on_error = error => console.error(
+  `\n[Fostrom] Error:\n  ${error.message}\n\n  Pass an \`on_error()\` callback in the config to handle errors.\n  See https://docs.fostrom.io/libs/js for more info.`
+)
+
+const on_fatal_error = error => {
+  console.error(
+    `\n[Fostrom] Fatal Error:\n  ${error.message}\n\n  Exiting. The default \`on_fatal_error\` handler calls \`process.exit(1)\`.\n  If you don't want the process to exit, pass an \`on_fatal_error()\` callback in the config.\n  See https://docs.fostrom.io/libs/js for more info.`
+  )
+
+  process.exit(1)
+}
+
+const on_msg = async (id, msg, pl) => {
+  console.log(`[Fostrom] Received Message: ID-${id}: ${msg} with payload: ${JSON.stringify(pl)}`)
+  return true
+}
+
+/* Validation Functions */
+
+function validate_fleet_id(fleet_id) {
+  if (!fleet_id) throw '[Fostrom] Fleet ID is required.'
+  if (fleet_id.length != 8) throw '[Fostrom] Fleet ID is invalid. Must be 8 characters long.'
+  if (id_regex.test(fleet_id)) throw '[Fostrom] Fleet ID is invalid. Must be alphanumeric.'
+  return fleet_id.toUpperCase()
+}
+
+function validate_device_id(device_id) {
+  if (!device_id) throw '[Fostrom] Device ID is required.'
+  if (device_id.length != 10) throw '[Fostrom] Device ID is invalid. Must be 10 characters long.'
+  if (id_regex.test(device_id)) throw '[Fostrom] Device ID is invalid. Must be alphanumeric.'
+  return device_id.toUpperCase()
+}
+
+function validate_device_secret(device_secret) {
+  if (!device_secret) throw '[Fostrom] Device Secret is required.'
+
+  if (device_secret.length != 36)
+    throw '[Fostrom] Device Secret is invalid. Must be 36 characters long and starts with `FOS-`.'
+
+  if (device_secret_regex.test(device_secret))
+    throw '[Fostrom] Device Secret is invalid. Must be 36 characters long and starts with `FOS-`.'
+
+  return device_secret.toUpperCase()
+}
+
+/* Default Config Functions */
+
+function get_puback_timeout(puback_timeout) {
+  if (!puback_timeout) return 30
+  if (puback_timeout > 60) return 60
+  if (puback_timeout < 10) return 10
+  if (!Number.isInteger(puback_timeout)) return 30
+  return puback_timeout
+}
+
+function get_transport(transport) {
+  if (!transport) return 'both'
+  if (transport == 'tcp') return 'tcp'
+  if (transport == 'ws') return 'ws'
+  return 'both'
+}
+
+function get_callbacks(config) {
+  return {
+    connected: config.on_connect || on_connect,
+    disconnected: config.on_disconnect || on_disconnect,
+    handle_error: config.on_error || on_error,
+    fatal_error: config.on_fatal_error || on_fatal_error,
+    handle_msg: config.on_msg || on_msg
+  }
+}
+
+function get_connect_urls(config) {
+  const fleet_id = config.fleet_id
+  let tcp_url = `mqtts://${fleet_id.toLowerCase()}.fleets.fostrom.dev:8883`
+  let ws_url = `wss://${fleet_id.toLowerCase()}.fleets.fostrom.dev/v1/mqtt`
+  let host = '127.0.0.1'
+
+  if (!!process.env.FOS_DEV_MODE) {
+    host = !!process.env.CONNECT_HOST ? process.env.CONNECT_HOST : '127.0.0.1'
+    tcp_url = `mqtt://${host}:8883`
+    ws_url = `ws://${host}:9999/v1/mqtt`
+  }
+
+  return { tcp_url, ws_url }
+}
+
+/* Exported Function */
+
+export function get_config(config) {
+  const { tcp_url, ws_url } = get_connect_urls(config)
+
+  return {
+    fleet_id: validate_fleet_id(config.fleet_id),
+    device_id: validate_device_id(config.device_id),
+    device_secret: validate_device_secret(config.device_secret),
+    keep_alive: !!config.keep_alive || true,
+    fetch_msgs: !!config.fetch_msgs || true,
+    require_puback: !!config.require_puback || true,
+    puback_timeout: get_puback_timeout(config.puback_timeout),
+    transport: get_transport(config.transport),
+    callbacks: get_callbacks(config),
+    tcp_url: tcp_url,
+    ws_url: ws_url
+  }
+}

package/index.js

@@ -0,0 +1,30 @@
+import { pack } from 'msgpackr'
+import { get_config } from './config.js'
+import { start } from './mqtt.js'
+
+class Fostrom {
+  constructor(config) {
+    this.config = get_config(config)
+    this.reconnect = true
+  }
+
+  async connect() {
+    this.client = await start(this, this.config)
+    return true
+  }
+
+  async close() {
+    this.reconnect = false
+    await this.client.endAsync()
+  }
+
+  async send_data(data) {
+    await this.client.publishAsync('d', pack(data), { qos: 1 })
+  }
+
+  async send_msg(msg, payload) {
+    await this.client.publishAsync('m', pack([msg, payload]), { qos: 1 })
+  }
+}
+
+export default Fostrom

package/license.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 HeadOn Labs LLP
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/mqtt.js

@@ -0,0 +1,130 @@
+import mqtt from 'mqtt'
+import { unpack, pack } from 'msgpackr'
+
+const invalid_device_creds_error = new Error(
+  'Invalid Device Credentials. Please re-check the device credentials.'
+)
+
+const network_error_msg = `[Fostrom] Failed to connect to Fostrom. Retrying in ${Math.round(retry_interval / 1000)} seconds...`
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+function get_mqtt_opts(config) {
+  return {
+    username: `${config.fleet_id}::${config.device_id}`,
+    password: config.device_secret,
+    clientId: 'MSGPACK',
+    keepalive: config.keep_alive == true ? 30 : 0,
+    reconnectPeriod: 0,
+    rejectUnauthorized: false
+  }
+}
+
+function backoff(interval) {
+  if (interval < 3000) { return 3000 }
+  if (interval == 3000) { return 5000 }
+  if (interval == 5000) { return 10000 }
+  if (interval == 10000) { return 15000 }
+  if (interval == 15000) { return 30000 }
+  return 30000
+}
+
+async function try_single_connect(config) {
+  try {
+    const url = config.transport == 'ws' ? config.ws_url : config.tcp_url
+    let client = await mqtt.connectAsync(url, get_mqtt_opts(config))
+    return client
+  } catch (e) {
+    return e.code == 5 ? 'unauthorized' : 'network_error'
+  }
+}
+
+async function try_fallback_connect(config) {
+  try {
+    let client = await mqtt.connectAsync(config.tcp_url, get_mqtt_opts(config))
+    return client
+  } catch (e) {
+    if (e.code == 5) {
+      return 'unauthorized'
+    } else {
+      await sleep(100)
+
+      try {
+        let client = await mqtt.connectAsync(config.ws_url, get_mqtt_opts(config))
+        return client
+      } catch (e) {
+        return e.code == 5 ? 'unauthorized' : 'network_error'
+      }
+    }
+  }
+}
+
+async function connect(config, retry_count = 0, retry_interval = 3000) {
+  const client_or_error = await config.transport == 'both' ?
+    try_fallback_connect(config) : try_single_connect(config)
+
+  if (client_or_error == 'unauthorized') {
+    config.callbacks.fatal_error(invalid_device_creds_error)
+  } else if (client_or_error == 'network_error') {
+    console.error(network_error_msg)
+    await sleep(retry_interval)
+    retry_count = retry_count + 1
+    retry_interval = retry_count <= 3 ? retry_interval : backoff(retry_interval)
+    return await connect(config, retry_count, retry_interval)
+  } else {
+    const client = client_or_error
+    return client
+  }
+}
+
+async function subscribe(config, client) {
+  if (config.fetch_msgs == true) {
+    try {
+      await client.subscribeAsync('m', { qos: 1 })
+      return true
+    } catch (e) {
+      let failed = new Error('Failed to subscribe to messages.')
+      failed.code = 2
+      config.callbacks.handle_error(failed)
+      return false
+    }
+  } else { return true }
+}
+
+function attachHooks(instance, config, client) {
+  client.on('close', async () => {
+    config.callbacks.disconnected()
+
+    if (instance.reconnect) {
+      console.error('[Fostrom] Disconnected. Reconnecting...')
+      await sleep(500)
+      instance.client = await start(instance, config)
+    }
+  })
+
+  client.on('message', async (_topic, message) => {
+    message = unpack(message)
+    const [id, msg, pl] = message
+
+    if (msg.startsWith('fos:') || msg.startsWith('fostrom:')) {
+      // Fostrom Internal Control Message
+    } else {
+      const ok = await config.callbacks.handle_msg(id, msg, pl)
+
+      if (ok !== false) {
+        await client.publishAsync('a', pack([id]), { qos: 1 })
+      } else {
+        // The message is not to be removed from the mailbox yet.
+      }
+    }
+  })
+}
+
+export async function start(instance, config) {
+  let client = await connect(config)
+  attachHooks(instance, config, client)
+  if (await subscribe(config, client)) { config.callbacks.connected() }
+  return client
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "fostrom",
+  "version": "0.0.1",
+  "description": "Fostrom's Official Device SDK for JS. Fostrom is an IoT Cloud Platform. Check it out on fostrom.io",
+  "keywords": [
+    "fostrom",
+    "device",
+    "sdk",
+    "iot",
+    "cloud",
+    "fleet",
+    "mqtt",
+    "websockets"
+  ],
+  "homepage": "https://docs.fostrom.io/libs/js",
+  "license": "MIT",
+  "author": "Fostrom <support@fostrom.io> (https://fostrom.io)",
+  "main": "index.js",
+  "type": "module",
+  "files": [
+    "index.js",
+    "mqtt.js",
+    "config.js"
+  ],
+  "dependencies": {
+    "mqtt": "^5.5.0",
+    "msgpackr": "^1.10.1"
+  }
+}

package/readme.md

@@ -0,0 +1,5 @@
+# Fostrom Device SDK
+
+Fostrom's Official Device SDK for JS. Fostrom is an IoT Cloud Platform. Check it out on [fostrom.io](https://fostrom.io).
+
+[Documentation available on fostrom.io](https://docs.fostrom.io/libs/js)