vertinho v0.3.0

Vertinho

Library to make conference apps and softphones through WebSockets with FreeSWITCH mod_verto.

Available on NPM: https://www.npmjs.com/package/vertinho

Tutorial

Soon. when it becomes stable and testable enough.

Licensing

The original Verto JS was written first depending of JQuery (and that's still the official version supported by FreeSWITCH team). It was made by Anthony Minessale II who copyrights it as Verto initial developer and created its backend code. Later, my friend Stefan Yohansson remade it without JQuery. Also were part of it Seven Du and Xueyun Jiang as contributors too and by extension the whole community. Until then, the code was under MPL 1.1.

However, I'm releasing Vertinho under MPL 2.0 (an upgrade explicitly allowed by the first license), a strong copyleft license compatible with GNU ones.

Asking why rewrite what was already "good and running"?

This is an indie fork of the original Verto JQuery, but it's not a pointless refactoring. Here are dozens of reasons if you're interested to know.

It's almost five years, frontend world had changed a lot, JS tools like JQuery are currently ephemeral. And one of my goals here is to help the FreeSWITCH community to follow the current JavaScript's state of the art.

So I'm specifically working on top of some problems that I encountered while coding with old Verto in the past months contributing for its core and fixing bugs of private forks. Disclaimer: I don't need to reveal closed source customizations or ideas here. People only break Verto because it's hard to understand how it works and how it's architetured. It's easier to make workarounds, patchs, adapters, shim layers... anything.

Here is what I intent to fix with Vertinho:

• It has static and outdated dependencies managed by manual "copy and paste":
  • like the JQuery itself or the WebRTC Adapter;
  • deprecated WebRTC API functions (like RTCPeerConnection.addStream which is now totally deprecated);
  • outdated WebRTC API usage (like MediaDevices.getUserMedia and RTCPeerConnection.createOffer that should be consumed using their Promise-based forms instead of passing callbacks as arguments).
• The library itself is not that good to be used as a dependency for others:
  • versioning is inexistent, depending entirely of FreeSWITCH releases;
  • no easily accessible changelogs;
  • almost an abandoned support of it on NPM package manager;
  • documentation consists only of a few examples that doesn't cover the entire API, since the people who wrote it aren't the same that developed it;
  • very redundant API (having more than one or two ways to change instance properties is confusing, specially when there are divergencies between them);
  • poorly parsed objects exposed (if you consume some of LiveArray messages, for example, you need to handle serialised JSON strings inside JS objects in arrays of unnamed data, which is more confusing than read this description);
  • bad error handling and messaging (for example, exceptions occured on a getUserMedia are always considered permission errors, which is not always true),
  • some ambiguous and implicit variable naming on exposed API (like res, e and pvt variables).
• Has too much responsibilities like manipulating the DOM:
  • most of JS UI libraries currently use Virtual DOM, then having Verto changing the DOM directly (like putting MediaStream into nodes from getElementById) could have been convenient in older days but today is just anti-pattern, causing conflicts and not helping that much;
  • having the library implicitly changing the UI style properties (like display to block or none) reduces the client developers control over their own applications.
• Lack of automated tests, making people afraid of changing code for paying technical debt or developing cutting edge features.
• Repository not in the same place as the majority of other JS libraries (i.e., GitHub), so is a less accessible for real frontend developers.
• License toxic for free source projects (old MPL is not GNU compatible).
• Difficult to debug issues on its core development:
  • great amount of side effects on the provided arguments (like the option useCamera being mutated from a string type into a document element);
  • a few side effects on internal methods (e.g., an inner getUserMedia that, despite being a getter, also acts as a setter and manipulates DOM);
  • weak transparency usage for parameters provided (e.g., useCamera is an unnecessary abstraction to browsers deviceId constraint);
  • a lot of unused variables and parameters;
  • greatly messed up indentation.

Seriously, why? Rewriting Verto JS helps me to study deeper how all of it works. I couldn't learn nor work with it properly if it's just black magic, accordingly with Clark's third law.

Also, I came from a land where simple is better than complex: