node-red-contrib-room-tools 1.4.2 → 1.5.0

package/README.md

@@ -9,6 +9,41 @@ One package containing three nodes:
 Every room gateway uses `/room-panel-api/regions/<room-id>` so additional
 regions follow the same URL structure.
 
+## Control traffic policy
+
+Version 1.5.0 uses the same control semantics at the panel, gateway and device
+driver boundaries:
+
+- `power`, `source`, `preset` and `mute` are discrete controls. The panel sends
+  them in order and the gateway never coalesces them.
+- `level`, `dimmer` and `position` are continuous controls. The panel sends at
+  most 25 updates per second, overwrites an unsent value for the same
+  `controlKey`, and sends the final value again on `change`/release.
+- The gateway independently enforces the same 40 ms latest-wins window. A
+  custom panel that produces too many slider events therefore cannot create an
+  unbounded downstream queue.
+- Every command emitted by the gateway includes validated `controlType`,
+  `controlKey` and `final` fields. Authentication, CSRF checks, room isolation
+  and value validation still happen before a command is accepted.
+
+The two deployed `ControlPanel` templates provide these reusable component
+methods: `sendDiscrete`, `sendContinuous`, `flushContinuous`,
+`scheduleContinuous` and `dispatchContinuous`. New controls should call the
+method matching their semantic type and use a stable key that identifies the
+room, target device and control number.
+
+```html
+<input
+  type="range"
+  @input="sendContinuous('level', 'audio/volume', 'rane/0/level/2', value)"
+  @change="flushContinuous('rane/0/level/2')"
+/>
+```
+
+```js
+sendDiscrete('mute', 'audio/mute', 'rane/0/mute/1', true)
+```
+
 The node type names and configuration fields are unchanged from the individual
 1.0.0 packages. No external dependencies or installation scripts are required.
 

package/gateway.cjs

@@ -1,109 +1,355 @@
 const crypto = require('node:crypto')
+
 const PREFIX = '/room-panel-api'
-const defaults = () => ({scene:'meeting',display:true,source:'无线投屏',volume:42,muted:false,light:80,curtains:75,temperature:23,meeting:false})
-const fields = {'display/power':'display','display/source':'source','audio/volume':'volume','audio/mute':'muted','lighting/brightness':'light','room/curtain':'curtains','climate/temperature':'temperature','room/scene':'scene','room/meeting':'meeting'}
-const ranges = {volume:[0,100],light:[0,100],curtains:[0,100],temperature:[16,30]}
+const CONTINUOUS_INTERVAL_MS = 40
+
+const defaults = () => ({
+  scene: 'meeting', display: true, source: '无线投屏', volume: 42,
+  muted: false, light: 80, curtains: 75, temperature: 23, meeting: false
+})
+
+const fields = {
+  'display/power': 'display',
+  'display/source': 'source',
+  'audio/volume': 'volume',
+  'audio/mute': 'muted',
+  'lighting/brightness': 'light',
+  'room/curtain': 'curtains',
+  'climate/temperature': 'temperature',
+  'room/scene': 'scene',
+  'room/meeting': 'meeting'
+}
+
+const controlPolicies = {
+  'display/power': { type: 'power', mode: 'discrete' },
+  'display/source': { type: 'source', mode: 'discrete' },
+  'audio/volume': { type: 'level', mode: 'continuous' },
+  'audio/mute': { type: 'mute', mode: 'discrete' },
+  'lighting/brightness': { type: 'dimmer', mode: 'continuous' },
+  'room/curtain': { type: 'position', mode: 'continuous' },
+  'climate/temperature': { type: 'position', mode: 'continuous' },
+  'room/scene': { type: 'preset', mode: 'discrete' },
+  'room/meeting': { type: 'preset', mode: 'discrete' },
+  'room/reset': { type: 'preset', mode: 'discrete' }
+}
+
+const ranges = {
+  volume: [0, 100], light: [0, 100], curtains: [0, 100], temperature: [16, 30]
+}
+
 const presets = {
-  focus:{light:85,curtains:80,volume:25,display:true},
-  cinema:{light:20,curtains:10,volume:65,display:true},
-  social:{light:70,curtains:80,volume:40,display:true},
-  unwind:{light:35,curtains:80,volume:32,display:true},
-  meeting:{light:80,curtains:75,volume:42,source:'无线投屏',display:true},
-  present:{light:30,curtains:10,volume:55,source:'HDMI 1',display:true},
-  video:{light:65,curtains:35,volume:65,source:'视频会议',display:true},
-  relax:{light:45,curtains:100,volume:20,source:'无线投屏',display:false}
+  focus: { light: 85, curtains: 80, volume: 25, display: true },
+  cinema: { light: 20, curtains: 10, volume: 65, display: true },
+  social: { light: 70, curtains: 80, volume: 40, display: true },
+  unwind: { light: 35, curtains: 80, volume: 32, display: true },
+  meeting: { light: 80, curtains: 75, volume: 42, source: '无线投屏', display: true },
+  present: { light: 30, curtains: 10, volume: 55, source: 'HDMI 1', display: true },
+  video: { light: 65, curtains: 35, volume: 65, source: '视频会议', display: true },
+  relax: { light: 45, curtains: 100, volume: 20, source: '无线投屏', display: false }
 }
-function valid(key, value) {
-  if(ranges[key]) return typeof value === 'number' && Number.isFinite(value) && value >= ranges[key][0] && value <= ranges[key][1]
-  if(['display','muted','meeting'].includes(key)) return typeof value === 'boolean'
-  if(key === 'source') return ['无线投屏','HDMI 1','HDMI 2','视频会议'].includes(value)
-  if(key === 'scene') return ['custom',...Object.keys(presets)].includes(value)
+
+function valid (key, value) {
+  if (ranges[key]) {
+    return typeof value === 'number' && Number.isFinite(value) &&
+      value >= ranges[key][0] && value <= ranges[key][1]
+  }
+  if (['display', 'muted', 'meeting'].includes(key)) return typeof value === 'boolean'
+  if (key === 'source') return ['无线投屏', 'HDMI 1', 'HDMI 2', '视频会议'].includes(value)
+  if (key === 'scene') return ['custom', ...Object.keys(presets)].includes(value)
   return false
 }
-function createGateway({username,password,room='room-01',onCommand=()=>{},secureCookie=false,prefix}) {
-  const routePrefix=prefix||PREFIX+'/regions/'+encodeURIComponent(room)
-  if(!username || typeof password !== 'string' || password.length < 12) throw Error('Set a username and password of at least 12 characters')
-  const salt=crypto.randomBytes(16), hash=crypto.scryptSync(password,salt,32)
-  const sessions=new Map(), attempts=new Map()
-  let state=defaults(), revision=0, closed=false
-  function feedback(msg) {
-    if(msg.room!==room || msg.kind!=='state') throw Error('Feedback requires matching room and kind=state')
-    const values=msg.topic==='room/state' ? msg.payload : fields[msg.topic] ? {[fields[msg.topic]]:msg.payload} : null
-    if(!values || typeof values!=='object' || Array.isArray(values) || !Object.keys(values).length || Object.entries(values).some(([k,v])=>!valid(k,v))) throw Error('Invalid feedback')
-    state={...state,...values};revision++
+
+function createLatestWinsDispatcher ({
+  onDispatch,
+  intervalMs = CONTINUOUS_INTERVAL_MS,
+  now = Date.now,
+  setTimer = setTimeout,
+  clearTimer = clearTimeout
+}) {
+  if (typeof onDispatch !== 'function') throw Error('onDispatch must be a function')
+  if (!Number.isFinite(intervalMs) || intervalMs < 0) throw Error('intervalMs must be non-negative')
+
+  const controls = new Map()
+  let closed = false
+
+  const schedule = (key, control) => {
+    if (closed || control.timer || !control.pending) return
+    const elapsed = control.lastSentAt === null ? intervalMs : now() - control.lastSentAt
+    const wait = Math.max(0, intervalMs - elapsed)
+    if (wait === 0) dispatch(key, control)
+    else control.timer = setTimer(() => dispatch(key, control), wait)
   }
-  function reply(res,status,data,headers={}) {
-    res.writeHead(status,{'Content-Type':'application/json; charset=utf-8','Cache-Control':'no-store','X-Content-Type-Options':'nosniff',...headers})
+
+  const dispatch = (key, control) => {
+    control.timer = null
+    if (closed || !control.pending) return
+    const message = control.pending
+    control.pending = null
+    control.lastSentAt = now()
+    onDispatch(message)
+    if (control.pending) schedule(key, control)
+  }
+
+  return {
+    push (key, message) {
+      if (closed) return false
+      let control = controls.get(key)
+      if (!control) {
+        control = { pending: null, timer: null, lastSentAt: null }
+        controls.set(key, control)
+      }
+      // 同一房间、设备、控制号始终最多只有一个尚未发送的连续目标。
+      control.pending = message
+      schedule(key, control)
+      return true
+    },
+    close () {
+      closed = true
+      for (const control of controls.values()) {
+        if (control.timer) clearTimer(control.timer)
+      }
+      controls.clear()
+    }
+  }
+}
+
+function createGateway ({
+  username,
+  password,
+  room = 'room-01',
+  onCommand = () => {},
+  secureCookie = false,
+  prefix,
+  continuousIntervalMs = CONTINUOUS_INTERVAL_MS
+}) {
+  const routePrefix = prefix || PREFIX + '/regions/' + encodeURIComponent(room)
+  if (!username || typeof password !== 'string' || password.length < 12) {
+    throw Error('Set a username and password of at least 12 characters')
+  }
+
+  const salt = crypto.randomBytes(16)
+  const hash = crypto.scryptSync(password, salt, 32)
+  const sessions = new Map()
+  const attempts = new Map()
+  const continuousDispatcher = createLatestWinsDispatcher({
+    onDispatch: onCommand,
+    intervalMs: continuousIntervalMs
+  })
+  let state = defaults()
+  let revision = 0
+  let closed = false
+
+  function feedback (msg) {
+    if (msg.room !== room || msg.kind !== 'state') {
+      throw Error('Feedback requires matching room and kind=state')
+    }
+    const values = msg.topic === 'room/state'
+      ? msg.payload
+      : fields[msg.topic] ? { [fields[msg.topic]]: msg.payload } : null
+    if (!values || typeof values !== 'object' || Array.isArray(values) ||
+      !Object.keys(values).length ||
+      Object.entries(values).some(([key, value]) => !valid(key, value))) {
+      throw Error('Invalid feedback')
+    }
+    state = { ...state, ...values }
+    revision++
+  }
+
+  function reply (res, status, data, headers = {}) {
+    res.writeHead(status, {
+      'Content-Type': 'application/json; charset=utf-8',
+      'Cache-Control': 'no-store',
+      'X-Content-Type-Options': 'nosniff',
+      ...headers
+    })
     res.end(JSON.stringify(data))
   }
-  async function body(req) {
-    if(!String(req.headers['content-type']||'').startsWith('application/json')) throw Error('JSON required')
-    if(req.body !== undefined) {
-      if(Buffer.isBuffer(req.body)) return JSON.parse(req.body.toString('utf8'))
-      if(typeof req.body === 'string') return JSON.parse(req.body)
-      if(req.body&&typeof req.body==='object'&&Object.keys(req.body).length)return req.body
+
+  async function body (req) {
+    if (!String(req.headers['content-type'] || '').startsWith('application/json')) {
+      throw Error('JSON required')
+    }
+    if (req.body !== undefined) {
+      if (Buffer.isBuffer(req.body)) return JSON.parse(req.body.toString('utf8'))
+      if (typeof req.body === 'string') return JSON.parse(req.body)
+      if (req.body && typeof req.body === 'object' && Object.keys(req.body).length) return req.body
+    }
+    let raw = ''
+    for await (const chunk of req) {
+      raw += chunk
+      if (Buffer.byteLength(raw) > 8192) throw Error('Request too large')
     }
-    let raw='';for await(const chunk of req){raw+=chunk;if(Buffer.byteLength(raw)>8192)throw Error('Request too large')}
     return JSON.parse(raw)
   }
-  const cookieName='room_panel_'+Buffer.from(room).toString('hex')
-  const cookie=(token,maxAge)=>`${cookieName}=${token}; Path=${routePrefix}; HttpOnly; SameSite=Strict; Max-Age=${maxAge}${secureCookie?'; Secure':''}`
-  async function handler(req,res) {
-    const path=new URL(req.url,'http://localhost').pathname
-    if(!path.startsWith(routePrefix+'/')) return false
-    if(closed){reply(res,503,{error:'Gateway unavailable'});return true}
+
+  const cookieName = 'room_panel_' + Buffer.from(room).toString('hex')
+  const cookie = (token, maxAge) => `${cookieName}=${token}; Path=${routePrefix}; HttpOnly; SameSite=Strict; Max-Age=${maxAge}${secureCookie ? '; Secure' : ''}`
+
+  async function handler (req, res) {
+    const path = new URL(req.url, 'http://localhost').pathname
+    if (!path.startsWith(routePrefix + '/')) return false
+    if (closed) {
+      reply(res, 503, { error: 'Gateway unavailable' })
+      return true
+    }
+
     try {
-      const now=Date.now()
-      for(const [id,s]of sessions)if(s.expiry<now)sessions.delete(id)
-      for(const [ip,a]of attempts)if(a.until<now)attempts.delete(ip)
-      if(req.method==='POST') {
-        const origin=req.headers.origin
-        if(!origin || new URL(origin).host!==req.headers.host){reply(res,403,{error:'Origin rejected'});return true}
+      const now = Date.now()
+      for (const [id, session] of sessions) if (session.expiry < now) sessions.delete(id)
+      for (const [ip, attempt] of attempts) if (attempt.until < now) attempts.delete(ip)
+
+      if (req.method === 'POST') {
+        const origin = req.headers.origin
+        if (!origin || new URL(origin).host !== req.headers.host) {
+          reply(res, 403, { error: 'Origin rejected' })
+          return true
+        }
       }
-      if(path===routePrefix+'/login' && req.method==='POST') {
-        const ip=req.socket.remoteAddress||'unknown', entry=attempts.get(ip)||{count:0,until:now+60000}
-        if(entry.count>=10 || attempts.size>1000){reply(res,429,{error:'Too many attempts. Wait one minute.'});return true}
-        entry.count++;attempts.set(ip,entry)
-        const data=await body(req)
-        const supplied=String(data.password||'')
-        if(supplied.length>256){reply(res,401,{error:'Invalid credentials'});return true}
-        const test=await new Promise((resolve,reject)=>crypto.scrypt(supplied,salt,32,(err,key)=>err?reject(err):resolve(key)))
-        const passwordMatch=crypto.timingSafeEqual(test,hash), usernameMatch=data.username===username
-        if(!passwordMatch||!usernameMatch){reply(res,401,{error:'Invalid credentials'});return true}
-        if(sessions.size>=100){reply(res,503,{error:'Session limit reached'});return true}
+
+      if (path === routePrefix + '/login' && req.method === 'POST') {
+        const ip = req.socket.remoteAddress || 'unknown'
+        const entry = attempts.get(ip) || { count: 0, until: now + 60000 }
+        if (entry.count >= 10 || attempts.size > 1000) {
+          reply(res, 429, { error: 'Too many attempts. Wait one minute.' })
+          return true
+        }
+        entry.count++
+        attempts.set(ip, entry)
+        const data = await body(req)
+        const supplied = String(data.password || '')
+        if (supplied.length > 256) {
+          reply(res, 401, { error: 'Invalid credentials' })
+          return true
+        }
+        const test = await new Promise((resolve, reject) => {
+          crypto.scrypt(supplied, salt, 32, (error, key) => error ? reject(error) : resolve(key))
+        })
+        const passwordMatch = crypto.timingSafeEqual(test, hash)
+        const usernameMatch = data.username === username
+        if (!passwordMatch || !usernameMatch) {
+          reply(res, 401, { error: 'Invalid credentials' })
+          return true
+        }
+        if (sessions.size >= 100) {
+          reply(res, 503, { error: 'Session limit reached' })
+          return true
+        }
         attempts.delete(ip)
-        const token=crypto.randomBytes(32).toString('hex'),csrf=crypto.randomBytes(24).toString('hex')
-        sessions.set(token,{csrf,expiry:now+8*3600000})
-        reply(res,200,{room,username,csrf},{'Set-Cookie':cookie(token,28800)});return true
+        const token = crypto.randomBytes(32).toString('hex')
+        const csrf = crypto.randomBytes(24).toString('hex')
+        sessions.set(token, { csrf, expiry: now + 8 * 3600000 })
+        reply(res, 200, { room, username, csrf }, { 'Set-Cookie': cookie(token, 28800) })
+        return true
+      }
+
+      const token = String(req.headers.cookie || '').split(';')
+        .map(value => value.trim())
+        .find(value => value.startsWith(cookieName + '='))
+        ?.split('=')[1]
+      const session = sessions.get(token)
+      if (!session) {
+        reply(res, 401, { error: 'Login required' })
+        return true
+      }
+      if (req.method === 'POST' && req.headers['x-room-csrf'] !== session.csrf) {
+        reply(res, 403, { error: 'CSRF rejected' })
+        return true
       }
-      const token=String(req.headers.cookie||'').split(';').map(v=>v.trim()).find(v=>v.startsWith(cookieName+'='))?.split('=')[1]
-      const session=sessions.get(token)
-      if(!session){reply(res,401,{error:'Login required'});return true}
-      if(req.method==='POST' && req.headers['x-room-csrf']!==session.csrf){reply(res,403,{error:'CSRF rejected'});return true}
-      if(path===routePrefix+'/session' && req.method==='GET'){reply(res,200,{room,username,csrf:session.csrf});return true}
-      if(path===routePrefix+'/state' && req.method==='GET') {
-        if(new URL(req.url,'http://localhost').searchParams.get('room')!==room){reply(res,403,{error:'Region denied'});return true}
-        reply(res,200,{room,kind:'state',topic:'room/state',payload:state,revision});return true
+      if (path === routePrefix + '/session' && req.method === 'GET') {
+        reply(res, 200, { room, username, csrf: session.csrf })
+        return true
       }
-      if(path===routePrefix+'/logout' && req.method==='POST'){sessions.delete(token);reply(res,200,{ok:true},{'Set-Cookie':cookie('',0)});return true}
-      if(path===routePrefix+'/command' && req.method==='POST') {
-        const data=await body(req)
-        if(data.room!==room){reply(res,403,{error:'Region denied'});return true}
-        const key=fields[data.topic]
-        if(data.topic==='room/reset' ? data.payload!==true : !key || !valid(key,data.payload) || (key==='scene' && !presets[data.payload])){reply(res,400,{error:'Invalid control value'});return true}
-        let next={...state}
-        if(data.topic==='room/reset')next=defaults()
-        else if(key==='scene')next={...next,...presets[data.payload],scene:data.payload}
-        else {next[key]=data.payload;if(['light','curtains'].includes(key))next.scene='custom';if(key==='meeting'&&data.payload)next.display=true}
-        // Identity and the complete command state are rebuilt on the server.
-        onCommand({room,topic:data.topic,payload:data.payload,kind:'command',user:username,state:next})
-        state=next;revision++
-        reply(res,200,{ok:true,revision});return true
+      if (path === routePrefix + '/state' && req.method === 'GET') {
+        if (new URL(req.url, 'http://localhost').searchParams.get('room') !== room) {
+          reply(res, 403, { error: 'Region denied' })
+          return true
+        }
+        reply(res, 200, { room, kind: 'state', topic: 'room/state', payload: state, revision })
+        return true
       }
-      reply(res,404,{error:'Not found'})
-    }catch(err){reply(res,400,{error:'Invalid request'})}
+      if (path === routePrefix + '/logout' && req.method === 'POST') {
+        sessions.delete(token)
+        reply(res, 200, { ok: true }, { 'Set-Cookie': cookie('', 0) })
+        return true
+      }
+      if (path === routePrefix + '/command' && req.method === 'POST') {
+        const data = await body(req)
+        if (data.room !== room) {
+          reply(res, 403, { error: 'Region denied' })
+          return true
+        }
+
+        const key = fields[data.topic]
+        const policy = controlPolicies[data.topic]
+        const invalidValue = data.topic === 'room/reset'
+          ? data.payload !== true
+          : !key || !valid(key, data.payload) || (key === 'scene' && !presets[data.payload])
+        const invalidType = data.controlType !== undefined && data.controlType !== policy?.type
+        const controlKey = data.controlKey === undefined ? data.topic : data.controlKey
+        const invalidControlKey = typeof controlKey !== 'string' ||
+          !/^[a-zA-Z0-9._:/-]{1,160}$/.test(controlKey)
+        if (!policy || invalidValue || invalidType || invalidControlKey ||
+          (data.final !== undefined && typeof data.final !== 'boolean')) {
+          reply(res, 400, { error: 'Invalid control value' })
+          return true
+        }
+
+        let next = { ...state }
+        if (data.topic === 'room/reset') next = defaults()
+        else if (key === 'scene') next = { ...next, ...presets[data.payload], scene: data.payload }
+        else {
+          next[key] = data.payload
+          if (['light', 'curtains'].includes(key)) next.scene = 'custom'
+          if (key === 'meeting' && data.payload) next.display = true
+        }
+
+        const command = {
+          room,
+          topic: data.topic,
+          payload: data.payload,
+          kind: 'command',
+          controlType: policy.type,
+          controlKey,
+          final: data.final === true,
+          user: username,
+          state: next
+        }
+
+        if (policy.mode === 'continuous') {
+          continuousDispatcher.push(room + ':' + controlKey, command)
+        } else {
+          onCommand(command)
+        }
+
+        state = next
+        revision++
+        reply(res, 200, { ok: true, revision })
+        return true
+      }
+
+      reply(res, 404, { error: 'Not found' })
+    } catch (error) {
+      reply(res, 400, { error: 'Invalid request' })
+    }
     return true
   }
-  return {handler,feedback,close(){closed=true;sessions.clear();attempts.clear()}}
+
+  return {
+    handler,
+    feedback,
+    close () {
+      closed = true
+      continuousDispatcher.close()
+      sessions.clear()
+      attempts.clear()
+    }
+  }
+}
+
+module.exports = {
+  CONTINUOUS_INTERVAL_MS,
+  PREFIX,
+  controlPolicies,
+  createGateway,
+  createLatestWinsDispatcher
 }
-module.exports={createGateway,PREFIX}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-red-contrib-room-tools",
-  "version": "1.4.2",
+  "version": "1.5.0",
   "description": "Room panel message generator and authenticated region gateway for Node-RED and MUSE Automator",
   "license": "UNLICENSED",
   "keywords": ["node-red"],