guacamole-common-js

guacamole-common-js is the browser-side client for the Apache Guacamole remote desktop gateway, packaged as an npm-installable fork of the official guacamole-client project. It implements the Guacamole protocol itself: parsing and dispatching instructions received over a tunnel, driving one or more canvas-based display layers, and exposing input devices (mouse, keyboard, touch, on-screen keyboard) and media consumers (audio player, video player, session recording) as separate modules attached to a shared Guacamole global namespace.

Because it only ships the combined JavaScript sources (the Java server, Maven build, and web application shell from the upstream monorepo are stripped out via .npmignore), it drops cleanly into any front-end project that needs to embed a Guacamole-powered remote desktop, VNC, RDP, SSH, or Telnet session without pulling in the rest of the Guacamole web application.

What You Get

• A Guacamole.Client that manages the connection lifecycle, keep-alive pings, and dispatch of incoming/outgoing Guacamole protocol instructions
• A pluggable Guacamole.Tunnel abstraction (with an HTTP tunnel implementation) so transport can be swapped or extended
• Guacamole.Display and Guacamole.Layer for compositing the remote desktop onto one or more canvas surfaces
• Input device modules — Guacamole.Mouse, Guacamole.Keyboard, Guacamole.Touch, Guacamole.OnScreenKeyboard — for capturing and forwarding user input
• Media modules — Guacamole.AudioPlayer, Guacamole.VideoPlayer, Guacamole.SessionRecording — for streamed audio/video and session playback
• Stream helpers (BlobReader/BlobWriter, StringReader/StringWriter, ArrayBufferReader/Writer, JSONReader) for the file-transfer and clipboard channels of the protocol

Common Use Cases

• Embedding a remote desktop viewer in a custom web application backed by a Guacamole server
• Building a self-service remote access portal for VNC/RDP/SSH hosts without exposing native remote-desktop clients
• Streaming and recording remote sessions for compliance or support/tech-assistance tooling
• Building bastion-host / jump-box web UIs that broker SSH or RDP access through a single browser-based entry point

Under The Hood

Architecture guacamole-common-js is organized as a flat set of prototype-based modules under src/main/webapp/modules/ (Client.js, Tunnel.js, Display.js, Keyboard.js, Mouse.js, Touch.js, OnScreenKeyboard.js, AudioPlayer.js, VideoPlayer.js, SessionRecording.js, plus stream helpers like BlobReader/BlobWriter/StringReader/StringWriter), all attached to a shared global Guacamole namespace declared once in Namespace.js. Guacamole.Client owns the connection lifecycle and instruction dispatch, delegating transport to a pluggable Guacamole.Tunnel implementation and rendering to Guacamole.Display, which composites one or more Guacamole.Layer canvas surfaces. Input devices (Mouse, Keyboard, Touch, OnScreenKeyboard) and media consumers (AudioPlayer, VideoPlayer, SessionRecording) are separate, loosely-coupled modules that attach to a Client or a DOM element and communicate through legacy on-callback properties layered on top of a newer Guacamole.Event/EventTarget system introduced for structured event dispatch. There is no dependency injection or internal module bundler — this is a build-time concatenation of independent files into a single distributable script, so architecture is expressed through composition and shared global state rather than an import graph. Changing Guacamole.Tunnel’s message-framing contract would ripple through every consumer, since Client, Display, and the stream reader/writer helpers all assume it.

Tech Stack The library has zero runtime dependencies and no framework — it is plain, pre-ES6 JavaScript (var-based prototypes, not classes) targeting browsers directly, packaged as both CommonJS and ESM builds (dist/cjs and dist/esm) via a two-step npm build script that concatenates the module sources and minifies them with the minify devDependency. There is no bundler (no webpack/Rollup/esbuild), no TypeScript, and no transpilation step — the shipped source is close to as-authored. The repo is itself a fork carved out of the larger Apache Guacamole client monorepo (predominantly Java/Maven for the server side), with this npm package extracting just the guacamole-common-js module for browser/npm consumers.

Code Quality Test coverage is minimal: a single Jasmine spec (EventSpec.js) exercises the Event/EventTarget system, but none of the larger modules (Client, Tunnel, Display, Keyboard, Mouse) have dedicated tests, and there is no visible linter or formatter configuration in the package. What the codebase does have consistently is thorough JSDoc — nearly every function, property, and constructor across all modules carries @param/@returns/@private annotations — which offsets some of the risk from the thin test suite by making behavior and contracts explicit at the source level. Error handling is largely implicit, relying on the Guacamole protocol’s own status/error instruction types rather than JS exceptions.

API Design The public surface is a set of constructor functions on a single global Guacamole namespace (Guacamole.Client, Guacamole.Tunnel, Guacamole.Display, Guacamole.Mouse, etc.), instantiated and wired together manually by the consumer — new Guacamole.Client(tunnel), then assigning client.onerror, display.onresize, and similar callback properties directly. This is a dated but predictable pattern: no Promises or async/await in the core API, and the legacy on-handler style sits alongside a newer structured Guacamole.Event system in some modules, meaning a new consumer has to learn two different conventions at once. Extensive JSDoc throughout meaningfully lowers the ramp-up cost despite the lack of TypeScript typings or higher-level abstractions.