Skip to content

Latest commit

 

History

History
142 lines (101 loc) · 4.29 KB

README.md

File metadata and controls

142 lines (101 loc) · 4.29 KB
title WASM Plugins
children
assemblyscript.md
rust.md
go.md
http_endpoints.md
deltas.md
capabilities.md
best_practices.md
integration_guide.md

WASM Plugin Development Guide

Overview

This guide covers how to develop WASM/WASIX plugins for Signal K Server. WASM plugins get isolated storage and capability-based permissions. The server's bindings enforce those capabilities; the plugins themselves run in Node.js's built-in WebAssembly runtime (node:wasi), which is not a security boundary for untrusted code.

What Makes a WASM Plugin?

A WASM plugin is an npm package that contains the WASM code for the plugin instead of the traditional JavaScript code. A WASM plugin is identified by the wasmManifest field in package.json:

{
  "name": "my-plugin-name",
  "wasmManifest": "plugin.wasm",
  "wasmCapabilities": { ... }
}

Key points:

  • wasmManifest (required): Path to the compiled .wasm file. This field tells Signal K to load this as a WASM plugin instead of a Node.js plugin.
  • wasmCapabilities (optional): Declares what permissions the plugin needs (network, storage, etc.). See Plugin Capabilities for the full list.
  • Package name (flexible): Can be anything - my-plugin, @myorg/my-plugin, etc. There is no requirement to use @signalk/ scope.
  • Keywords: Include both signalk-node-server-plugin and signalk-wasm-plugin. The App Store finds every plugin by signalk-node-server-plugin; signalk-wasm-plugin marks it as a WASM plugin.

Language Options

Signal K Server supports multiple languages for WASM plugin development:

  • AssemblyScript - TypeScript-like syntax, easiest for JS/TS developers, smallest binaries (3-10 KB)
  • Rust - Best performance and tooling, medium binaries (50-200 KB)
  • Go/TinyGo - Go via TinyGo compiler, medium binaries (50-150 KB)

Why WASM Plugins?

Benefits

  • Capability-based access: A plugin reaches the server, the network and sockets only through the bindings its declared capabilities enable
  • Multi-language: Write plugins in Rust, AssemblyScript, and more
  • Crash isolation: Plugin crashes don't affect server
  • Performance: Near-native performance with WASM
  • Self contained: WASM plugins do not install any additional dependencies
  • Small binaries (compared to native options): 3-200 KB depending on language

Current Capabilities

  • Delta Emission: Send SignalK deltas to update vessel data
  • Status & Error Reporting: Set plugin status and error messages
  • Configuration: The same JSON schema-based configuration as JS plugins
  • Data Storage: VFS-isolated file storage
  • HTTP Endpoints: Register custom REST API endpoints
  • Static Files: Serve a web UI from the public/ directory (with the signalk-webapp keyword)
  • Network Access: HTTP requests via as-fetch (AssemblyScript)
  • Resource Providers: Serve SignalK resources
  • Weather Providers: Integrate with Signal K Weather API
  • Radar Providers: Integrate with Signal K Radar API

Choose Your Language

AssemblyScript - Recommended for JS/TS Developers

Best for:

  • Quick prototypes
  • Simple data processing
  • Migrating existing Node.js plugins
  • Developers familiar with TypeScript

Pros:

  • TypeScript-like syntax
  • Fast development
  • Smallest binaries (3-10 KB)
  • Familiar tooling (npm)

Cons:

  • Smaller ecosystem than Rust
  • Some TypeScript features unavailable
  • Manual memory management

Jump to AssemblyScript Guide

Rust - Recommended for Performance-Critical Plugins

Best for:

  • Performance-critical plugins
  • Complex algorithms
  • Low-level operations
  • Production plugins

Pros:

  • Best performance
  • Memory safety
  • Rich ecosystem
  • Strong typing

Cons:

  • Steeper learning curve
  • Longer compile times
  • Larger binaries (50-200 KB)

Jump to Rust Guide

Go/TinyGo - For Go Developers

Best for:

  • Go developers wanting to write plugins
  • Medium complexity plugins
  • Resource providers with hybrid patterns

Pros:

  • Familiar Go syntax
  • Good standard library support
  • Medium binaries (50-150 KB)
  • Strong typing

Cons:

  • Requires TinyGo (not standard Go)
  • Some Go features unavailable
  • Slower than Rust

Jump to Go/TinyGo Guide