Forem: Huakun Shen

Tauri Without Electron Bloat: A Type-Safe JS Runtime Bridge with `tauri-plugin-js`

Huakun Shen — Tue, 24 Feb 2026 22:03:59 +0000

Tauri Without Electron Bloat: A Type-Safe JS Runtime Bridge with `tauri-plugin-js`

https://github.com/HuakunShen/tauri-plugin-js.git

If you love Tauri's small footprint but still need a real JavaScript runtime process, you usually hit a wall: webview code is not enough for some workloads (native modules, long-running compute, local AI tooling, heavyweight filesystem orchestration). This repo shows a clean way around that wall.

tauri-plugin-js gives a Tauri v2 app a managed process layer for Bun, Node.js, and Deno, while keeping RPC strongly typed through kkrpc. The key design choice is simple and powerful: Rust handles lifecycle and I/O transport, but the RPC protocol remains end-to-end JavaScript.

The architecture in one sentence

Rust is a process/event relay, JavaScript is the RPC protocol owner.

You can see this split directly in the code:

Process management and stdio relay live in src/desktop.rs.
Tauri command surface is in src/commands.rs, registered in src/lib.rs.
Frontend transport adapter + API wrappers are in guest-js/index.ts.

That split avoids protocol duplication in Rust and keeps your app-level API types in TypeScript where your frontend and worker code already live.

Why this model works better than ad-hoc sidecar wiring

Most sidecar implementations eventually re-invent three things:

Process lifecycle management
Message framing and stream handling
Typed request/response contracts

This plugin hardens all three.

1) Lifecycle is first-class, not an afterthought

The plugin exposes commands such as spawn, kill, kill_all, restart, list_processes, get_status, write_stdin, detect_runtimes, set_runtime_path, and get_runtime_paths (src/lib.rs, src/commands.rs).

On app exit, it force-cleans all child processes in the plugin event hook (src/lib.rs), preventing orphaned workers.

2) Stream transport has production-grade edge handling

Two subtle but critical details are implemented in guest-js/index.ts:

Newline framing restoration: Rust uses BufReader::lines() (src/desktop.rs), which strips trailing \n. The JS adapter re-appends \n before handing messages to kkrpc.
No spin-loop on teardown: JsRuntimeIo.read() returns a never-resolving promise when destroyed, paired with isDestroyed semantics used by kkrpc's channel loop. This prevents CPU spin when a channel is torn down.

These are exactly the kind of tiny transport bugs that make IPC feel flaky in real apps.

3) Type-safe API remains shared across UI and workers

In the example app, one interface (examples/tauri-app/backends/shared-api.ts) drives calls from Svelte UI to Bun/Node/Deno workers. The same typed calls (createChannel<..., BackendAPI>) are used regardless of runtime (examples/tauri-app/src/App.svelte).

Runtime mode vs sidecar mode: practical deployment strategy

This repo demonstrates both paths clearly.

Runtime mode (great for dev)

Use spawn({ runtime, script, cwd }) to run source workers directly.

In dev, scripts resolve from backends/ (resolve("..", "backends")) in examples/tauri-app/src/App.svelte.
Runtime availability is probed via detectRuntimes() and rendered in UI.

Sidecar mode (great for distribution)

Compile workers into standalone binaries and spawn with spawn({ sidecar: "name" }).

The sidecar resolution logic in src/desktop.rs is especially solid:

Tries plain binary name next to app executable (production bundle behavior).
Falls back to target-triple suffix ({name}-{triple}) for development.
Includes Windows .exe variants.

This allows one frontend API while supporting both dev and packaged execution models.

The Deno compile trap (and the clean workaround)

One of the most valuable implementation lessons in this repo:

deno compile is intentionally run from a separate package (examples/deno-compile/), not from examples/tauri-app/backends/.
The separate package has its own deno.json import map (examples/deno-compile/deno.json).

The build script (examples/tauri-app/scripts/build-sidecars.sh) compiles:

Bun sidecar from backends/bun-worker.ts
Deno sidecar from ../../deno-compile/main.ts

This separation avoids compilation behavior that can go wrong in directories containing node_modules.

A small but smart DX trick: placeholder resources

examples/tauri-app/scripts/ensure-resources.sh creates placeholder files for:

externalBin targets
bundled workers/* resources

Why this matters: tauri dev can fail if configured assets do not exist yet. Creating placeholders keeps local dev bootable before running sidecar/resource build scripts.

The corresponding config is visible in examples/tauri-app/src-tauri/tauri.conf.json (externalBin + resources).

Multi-window behavior is naturally supported

Capability config includes "main" and "window-*" (examples/tauri-app/src-tauri/capabilities/default.json), and the example UI can spawn extra windows via WebviewWindow (examples/tauri-app/src/App.svelte).

Because process events are emitted through Tauri's event system and process names are explicit, windows can share backend workers without inventing custom routing layers in Rust.

Code-level flow from click to typed result

Frontend calls spawn(name, config) via wrapper in guest-js/index.ts.
Rust plugin launches child process and stores process entry in map (src/desktop.rs).
Rust emits stdout/stderr/exit events (js-process-stdout, js-process-stderr, js-process-exit).
Frontend JsRuntimeIo listens to process-specific events and feeds kkrpc transport.
createChannel returns typed remote API proxy.
UI calls api.add, api.echo, api.getSystemInfo, api.fibonacci (examples/tauri-app/src/App.svelte).

No protocol parsing in Rust, no duplicated schemas, no ad-hoc JSON glue per method.

What to copy into your own Tauri app

If you are adopting this pattern, keep these decisions:

Keep Rust transport-thin; do not parse RPC payloads in Rust.
Preserve newline message framing across stdio boundaries.
Enforce teardown semantics (isDestroyed) in your IO adapter.
Support both runtime and sidecar execution paths behind one frontend API.
Keep Deno compile inputs in a dedicated Deno package.
Add dev-time placeholder generation for configured bundle assets.

If you copy only one thing: copy the transport discipline in guest-js/index.ts and the sidecar resolution strategy in src/desktop.rs.

References

Repo sources

README.md
SKILL.md
src/lib.rs
src/commands.rs
src/desktop.rs
guest-js/index.ts
examples/tauri-app/README.md
examples/tauri-app/src/App.svelte
examples/tauri-app/scripts/build-sidecars.sh
examples/tauri-app/scripts/build-workers.sh
examples/tauri-app/scripts/ensure-resources.sh
examples/tauri-app/src-tauri/tauri.conf.json
examples/tauri-app/src-tauri/capabilities/default.json
examples/deno-compile/deno.json
examples/deno-compile/main.ts

External docs (for production hardening)

Tauri v2 permissions: https://v2.tauri.app/security/permissions/
Tauri capabilities: https://v2.tauri.app/reference/acl/capability/
Tauri sidecars: https://v2.tauri.app/develop/sidecar/
kkrpc docs: https://docs.kkrpc.kunkun.sh/

Building a Local-First Tauri App with Drizzle ORM, Encryption, and Turso Sync (tauri-plugin-libsql)

Huakun Shen — Tue, 24 Feb 2026 21:45:58 +0000

Building a Local-First Tauri App with Drizzle ORM, Encryption, and Turso Sync

https://github.com/HuakunShen/tauri-plugin-libsql

I've been building desktop apps with Tauri for a while now, and one thing that consistently caused friction was the database layer. Tauri's official @tauri-apps/plugin-sql gets you SQLite, but it has no encryption support and no Drizzle integration that actually works inside a WebView. So I built my own plugin — tauri-plugin-libsql — and this post covers why I built it, the design decisions I made, and a few genuinely weird bugs I ran into along the way.

The Problem with Databases in Tauri

Tauri apps run your UI in a WebView. That WebView is essentially a browser — it has no Node.js fs module, no native bindings, no ability to open SQLite files directly. All access to the filesystem has to go through Tauri's IPC layer: your TypeScript code calls invoke(), and a Rust command handler does the actual work.

The official plugin, @tauri-apps/plugin-sql, handles this. It's fine for basic use. But I kept running into three walls:

1. No encryption. The plugin uses sqlx under the hood, and sqlx doesn't support SQLite encryption. If you want an encrypted database — say, to protect user data if the device is lost — you're on your own.

2. Drizzle ORM's migrator doesn't work in a WebView. I love Drizzle. Type-safe queries, a clean migration workflow, great ergonomics. But Drizzle's built-in migrator calls readMigrationFiles(), which uses Node's fs module at runtime. That API doesn't exist in a WebView. You hit a wall immediately when you try to use drizzle-kit migrate in a Tauri app.

3. No Turso support. I wanted to build local-first apps — data lives on disk, works offline, but syncs to a cloud database when connected. Turso's embedded replica mode does exactly this, but @tauri-apps/plugin-sql has no concept of it.

Why libsql

libsql is Turso's fork of SQLite. For the purposes of a Tauri plugin, it offers three things the standard sqlite3 crate doesn't:

Native encryption via the encryption feature flag — AES-256-CBC, no extra native libraries
Embedded replica mode — local SQLite file that syncs bidirectionally with Turso cloud
A clean async Rust API with a builder pattern that makes the three modes (local, replica, remote) easy to configure

The Rust API looks like this:

// Local only
let db = Builder::new_local("myapp.db").build().await?;

// Embedded replica (local file + Turso sync)
let db = Builder::new_remote_replica("local.db", "libsql://mydb.turso.io", "token")
    .build().await?;

// Initial sync on connect
db.sync().await?;

Making Drizzle Work in a WebView

Drizzle has a lesser-known driver called sqlite-proxy. Instead of opening a database file directly, you give Drizzle a callback function. Drizzle generates SQL queries, calls your function with them, and you return the results. It was designed for HTTP-based SQLite proxies, but it works perfectly for Tauri's invoke() pattern.

import { drizzle } from "drizzle-orm/sqlite-proxy";
import { invoke } from "@tauri-apps/api/core";

const proxy = async (sql: string, params: unknown[], method: string) => {
  if (method === "run") {
    const result = await invoke("plugin:libsql|execute", { db: path, query: sql, values: params });
    return { rows: [] };
  }
  const rows = await invoke("plugin:libsql|select", { db: path, query: sql, values: params });
  return { rows: rows.map(Object.values) };
};

const db = drizzle(proxy, { schema });

The plugin exports createDrizzleProxy(path) which wraps this pattern. You get full Drizzle — type-safe queries, joins, transactions, all of it — running against a local SQLite file via Rust, inside a Tauri WebView.

Solving the Migration Problem

Once Drizzle works, you want migrations. The standard drizzle-kit migrate reads .sql files from disk at runtime. In a WebView: no filesystem, no fs, dead end.

The solution is Vite's import.meta.glob. Instead of reading files at runtime, Vite inlines the SQL file contents directly into the JavaScript bundle at build time:

const migrations = import.meta.glob<string>("./drizzle/*.sql", {
  eager: true,
  query: "?raw",      // import as raw string
  import: "default",
});

This gives you an object like { "./drizzle/0000_init.sql": "CREATE TABLE ...", ... }. You pass it to migrate(), which tracks applied migrations in a __drizzle_migrations table and runs pending ones in order:

await Database.load("sqlite:myapp.db");
await migrate("sqlite:myapp.db", migrations);

// Now safe to use Drizzle
const db = drizzle(createDrizzleProxy("sqlite:myapp.db"), { schema });

The order matters. Querying before migrate() runs gives you "no such table" errors.

Encryption

The plugin supports two modes:

Plugin-level encryption — configured once in Rust, applies to all databases. The key never touches JavaScript:

let config = tauri_plugin_libsql::Config {
    base_path: Some(cwd),
    encryption: Some(EncryptionConfig {
        cipher: Cipher::Aes256Cbc,
        key: std::env::var("DB_KEY")
            .map(|k| k.into_bytes())
            .unwrap_or_default(),
    }),
};

tauri::Builder::default()
    .plugin(tauri_plugin_libsql::init_with_config(config))

Per-database encryption — key passed from the frontend:

const db = await Database.load({
  path: "sqlite:secrets.db",
  encryption: {
    cipher: "aes256cbc",
    key: Array.from(myUint8Key32Bytes),
  },
});

Plugin-level is the better choice for most apps — it keeps the key in Rust where JavaScript can't inspect it.

Turso Embedded Replica

This is where things get interesting. Turso's embedded replica mode maintains a local SQLite file that stays in sync with a Turso cloud database. Reads come from the local file (fast, offline-capable). Writes go to the remote. You pull the latest changes manually with sync().

For a Tauri app, this is the ideal architecture. Your app works offline by default. When the user is connected, you sync on launch and on demand.

const db = await Database.load({
  path: "sqlite:local.db",
  syncUrl: "libsql://mydb-org.turso.io",
  authToken: import.meta.env.VITE_TURSO_AUTH_TOKEN,
});

// migrations run against the local replica
await migrate(db.path, migrations);

// pull latest remote changes
await db.sync();

Database.load() does an initial sync automatically on connect. Subsequent db.sync() calls pull incremental changes.

The Weird Bugs

Building this plugin involved a few bugs that were interesting enough to be worth writing up.

Bug 1: The IPC That Never Responded

After adding Turso support, I noticed that connecting with a badly-formatted URL caused the app to hang indefinitely on the loading spinner. The Rust terminal showed a panic:

thread 'tokio-runtime-worker' panicked at libsql-0.9.29/src/database/builder.rs:409:66:
called `Result::unwrap()` on an `Err` value: http::Error(InvalidUri(InvalidFormat))

libsql's builder calls unwrap() internally when parsing the sync URL. This isn't a bug in the user's code — it's libsql panicking on an Err it should have returned. In Tauri, a panic inside an async command handler causes the IPC response to never be sent. The JavaScript await hangs forever. There's no timeout, no rejection — just silence.

The fix is catch_unwind from the futures crate:

use futures::FutureExt;
use std::panic::AssertUnwindSafe;

let db = AssertUnwindSafe(async move {
    // ... libsql builder calls ...
})
.catch_unwind()
.await
.map_err(|_| Error::InvalidDbUrl(
    "libsql panicked — check your URL format".into()
))??;

The double ?? unwraps the panic result first (converted to Error), then the inner Result<Database, Error>. Now a bad URL gives a real error message instead of hanging.

Bug 2: `execute_batch` Silently Failing with Embedded Replicas

The migration runner originally used execute_batch() from libsql to run multiple SQL statements atomically. This worked fine for local databases. With an embedded replica, migrations appeared to succeed — no errors — but the tables didn't actually get created. The Drizzle migrations table would record the migration as applied, then the next query would fail with "no such table".

After a lot of debugging, it turned out that execute_batch() doesn't correctly route writes through the embedded replica's write path in libsql 0.9.x. Individual execute() calls inside an explicit BEGIN/COMMIT do work:

pub async fn batch(&self, queries: Vec<String>) -> Result<(), Error> {
    self.conn.execute("BEGIN", Params::None).await?;
    for query in &queries {
        if let Err(e) = self.conn.execute(query.as_str(), Params::None).await {
            let _ = self.conn.execute("ROLLBACK", Params::None).await;
            return Err(Error::Libsql(e));
        }
    }
    if let Err(e) = self.conn.execute("COMMIT", Params::None).await {
        let _ = self.conn.execute("ROLLBACK", Params::None).await;
        return Err(Error::Libsql(e));
    }
    Ok(())
}

Tedious, but it works reliably.

Bug 3: The `$state` That Wasn't

This one was a Svelte 5 mistake in the demo app. I had let dbInstance: Database | null = null — a plain mutable variable, not a $state. The code that checked {#if dbInstance} in the template to show the "Reset DB" button was therefore non-reactive. Setting dbInstance in onMount had no effect on the template.

<!-- Before: dbInstance not reactive, button never shows -->
let dbInstance: Database | null = null;

<!-- After: reactive, button appears when DB is loaded -->
let dbInstance = $state<Database | null>(null);

Svelte 5 doesn't warn about this in all cases — if the variable is set in onMount and never re-assigned elsewhere, you might not get a warning. The template just silently doesn't update.

Bug 4: Error State That Ate the Form

The CRUD error handling set error = "Failed to add: ..." on failures. The template used {:else if error} to show an error alert — which meant any failed add/toggle/delete replaced the entire todo form with the alert. The user had to refresh to get the form back.

The fix was to stop mixing fatal errors (load failure — should block the UI) with transient errors (write failure — should be a notification). Toast notifications handle the transient case; error state is now only set on fatal load failures.

The Demo App

The plugin ships with a two-panel demo that makes the local vs. remote difference tangible:

Left panel: Local SQLite. Writes are instant.
Right panel: Turso embedded replica. Enter your syncUrl and auth token, click Connect. Writes go to Turso — you can watch the latency.

Both panels share the same TodoList.svelte component. The difference is just which props are passed:

<!-- Local: instant writes -->
<TodoList dbFile="todos.db" position="bottom-left" />

<!-- Turso: network-latency writes -->
<TodoList
  dbFile="todos-turso.db"
  syncUrl={appliedSyncUrl}
  authToken={appliedAuthToken}
  position="bottom-right"
  onDisconnect={handleDisconnect}
/>

The position prop routes sonner toasts to different corners so you can see which panel's events are which.

Installation

If you want to try it:

# src-tauri/Cargo.toml
[dependencies]
tauri-plugin-libsql = "0.1.0"

# For Turso sync:
tauri-plugin-libsql = { version = "0.1.0", features = ["replication"] }

npm install tauri-plugin-libsql-api

// src-tauri/src/lib.rs
tauri::Builder::default()
    .plugin(tauri_plugin_libsql::init())
    .run(tauri::generate_context!())
    .expect("error while running tauri application");

The source is on GitHub. Contributions welcome, especially testing on Windows and Linux.

What's Next

A few things I'd like to add:

Auto-sync on network reconnect — Tauri has network status events; db.sync() could fire automatically
Conflict visibility — embedded replica is last-write-wins with no conflict UI
iOS/Android testing — the mobile stubs exist but haven't been verified

If you're building a Tauri app and have hit the same walls with the official SQL plugin, give it a try.

drizzle + sqlite in Tauri App

Huakun Shen — Thu, 20 Mar 2025 13:01:44 +0000

GitHub: https://github.com/HuakunShen/tauri-demo/tree/master/examples/drizzle-sqlite-proxy

This demo let you use drizzle to control your sqlite DB in a Tauri app, without any sidecar.
This is a Tauri v2 reproduction for the archived repo https://github.com/tdwesten/tauri-drizzle-sqlite-proxy-demo

Tauri's backend is in Rust, so I always thought the only way to use sqlite ORM in a Tauri app is with projects like diesel or prisma-client-rust, which could be hard because they are in rust.
What is even harder is sqlite db encryption. Both of the 2 ORMs don't support cipher encryption, thus I had to write raw sql queries in kunkun Example
Maintaining raw sql queries is a nightmare to me, especially when it comes to schema migration.
I have to rely on thorough testing to make sure everything is correct. There is no type checking.

I never knew it's possible to use TypeScript ORM like drizzle in Tauri without a sidecar.
In my project kkrpc I implemented a Tauri adapter and made it possible to use compiled TypeScript backend as a sidecar in a Tauri app. With kkrpc, it's easy to call TypeScript backend from frontend. I can use any TypeScript libraries in a compiled deno/bun/node binary, including drizzle.
However that introduces at least 60MB to the bundle size. It's a good deal if you can take advantage of many node packages, but not really worth it for just DB.

Then I found this project https://github.com/tdwesten/tauri-drizzle-sqlite-proxy-demo using drizzle proxy to send queries to Tauri's sql plugin.
Drizzle Proxy Docs: https://orm.drizzle.team/docs/connect-drizzle-proxy

Basically, it's a translator between the tauri-plugin-sql and drizzle ORM.
drizzle computes the sql query in frontend and send the query + params to backend to execute.
The backend can be a http server, or Tauri core.

// Example of driver implementation
import { drizzle } from 'drizzle-orm/pg-proxy';

const db = drizzle(async (sql, params, method) => {
  try {
    const rows = await axios.post('http://localhost:3000/query', { sql, params, method });

    return { rows: rows.data };
  } catch (e: any) {
    console.error('Error from pg proxy server: ', e.response.data)
    return { rows: [] };
  }
});

Here is real code

import { drizzle } from "drizzle-orm/sqlite-proxy";
import Database from "@tauri-apps/plugin-sql";
import * as schema from "./schema";

export async function getDb() {
  return await Database.load("sqlite:test.db");
}

export const db = drizzle<typeof schema>(
  async (sql, params, method) => {
    const sqlite = await getDb();
    let rows: any = [];
    let results = [];

    // If the query is a SELECT, use the select method
    if (isSelectQuery(sql)) {
      rows = await sqlite.select(sql, params).catch((e) => {
        console.error("SQL Error:", e);
        return [];
      });
    } else {
      // Otherwise, use the execute method
      rows = await sqlite.execute(sql, params).catch((e) => {
        console.error("SQL Error:", e);
        return [];
      });
      return { rows: [] };
    }

    rows = rows.map((row: any) => {
      return Object.values(row);
    });

    // If the method is "all", return all rows
    results = method === "all" ? rows : rows[0];
    await sqlite.close();
    return { rows: results };
  },
  // Pass the schema to the drizzle instance
  { schema: schema, logger: true }
);

And here is how it can be used (just like regular drizzle code)

const loadUsers = async () => {
  db.query.users
    .findMany()
    .execute()
    .then((results) => {
      console.log("🚀 ~ FindMany response from Drizzle:", results);
      users = results;
    });
};

async function addUser() {
  await db.insert(schema.users).values({ name: nameInput });
  nameInput = "";
  loadUsers();
}

Build a free ip info cache with PocketBase

Huakun Shen — Thu, 13 Mar 2025 04:07:09 +0000

GitHub Repo: https://github.com/HuakunShen/ip-info-cache-pb

In some of my projects, I need to visualize IP addresses on a map, thus I will need to get the longitude and latitude of the IP address.

IP info APIs costs money. e.g. ipgeolocation.io has a free tier of 30k requests/month.

It's hard to request 30k unique ips in a month, but if the same ip address is checked frequently the free quota could be used up quickly. Thus I built this simple cache server. This cache server is used as a proxy server, requests sent to /api/info/<:ip> is forwarded to API service and cached in pocketbase.

Why Pocketbase?

Key value DB like redis is usually used for caching, however Redis memory is expensive.
We may need to store millions of ip addresses.

Pockethost provides free pocketbase service. So I deployed a pocketbase service on pockethost and built this simple cache server.

Sample Response

{
  "calling_code": "+61",
  "city": "South Brisbane",
  "connection_type": "",
  "continent_code": "OC",
  "continent_name": "Oceania",
  "country_capital": "Canberra",
  "country_code2": "AU",
  "country_code3": "AUS",
  "country_emoji": "🇦🇺",
  "country_flag": "https://ipgeolocation.io/static/flags/au_64.png",
  "country_name": "Australia",
  "country_name_official": "Commonwealth of Australia",
  "country_tld": ".au",
  "currency": {
    "code": "AUD",
    "name": "Australian Dollar",
    "symbol": "A$"
  },
  "district": "Brisbane",
  "geoname_id": "10113228",
  "ip": "1.1.1.1",
  "is_eu": false,
  "isp": "APNIC Research and Development",
  "languages": "en-AU",
  "latitude": "-27.47306",
  "longitude": "153.01421",
  "organization": "Cloudflare, Inc.",
  "state_code": "AU-QLD",
  "state_prov": "Queensland",
  "time_zone": {
    "current_time": "2025-03-08 06:13:39.206+1000",
    "current_time_unix": 1741378419.206,
    "dst_end": "",
    "dst_exists": false,
    "dst_savings": 0,
    "dst_start": "",
    "is_dst": false,
    "name": "Australia/Brisbane",
    "offset": 10,
    "offset_with_dst": 10
  },
  "zipcode": "4101"
}

NestJS + Neo4j + GraphQL Setup

Huakun Shen — Thu, 13 Mar 2025 04:04:57 +0000

GraphQL Schema
NestJS Server Configuration
- GraphQL Module
Codegen

GitHub Repo: https://github.com/HuakunShen/nestjs-neo4j-graphql-demo

I haven't found a good update-to-date example of using Neo4j with NestJS and GraphQL. So I decided to write one myself.

Neo4j's graphql library has updated its API, some examples I found online were outdated (https://neo4j.com/developer-blog/creating-api-in-nestjs-with-graphql-neo4j-and-aws-cognito/). This demo uses v5.x.x.

GraphQL Schema

type Mutation {
  signUp(username: String!, password: String!): String
  signIn(username: String!, password: String!): String
}

# Only authenticated users can access this type
type Movie @authentication {
  title: String
  actors: [Actor!]! @relationship(type: "ACTED_IN", direction: IN)
}

# Anyone can access this type
type Actor {
  name: String
  movies: [Movie!]! @relationship(type: "ACTED_IN", direction: OUT)
}

# Only authenticated users can access this type
type User @authentication {
  id: ID! @id
  username: String!
  # this is just an example of how to use @authorization to restrict access to a field
  # If you list all users without the plaintextPassword field, you will see all users
  # If you list all users with the plaintextPassword field, you will only see the user whose id matches the jwt.sub (which is the id of the authenticated user)
  # in reality, never store plaintext passwords in the database
  plaintextPassword: String!
    @authorization(filter: [{ where: { node: { id: "$jwt.sub" } } }])
  password: String! @private
}

NestJS Server Configuration

GraphQL Module

A GraphQL module can be generated with bunx nest g mo graphql.

Here is the configuration. In new Neo4jGraphQL(), authorization key is provided for JWT auth. Queries can be restricted by adding @authentication or @authorization to the type.

One important thing to note is the custom auth resolvers. Neo4jGraphQL auto-generate types, queries, mutations implementations for the types in the schema to provide basic CRUD operations, but custom functions like sign in and sign up must be implemented separately. Either as regular REST endpoints in other modules or provide a custom resolver to the Neo4jGraphQL instance.

Usually in NestJS, you would add resolvers to the providers list of the module, but in this case, the resolvers must be added to the Neo4jGraphQL instance. Otherwise you will see the custom queries defined in schema in the playground, but they always return null.

@Module({
  imports: [
    GraphQLModule.forRootAsync<ApolloDriverConfig>({
      driver: ApolloDriver,
      useFactory: async () => {
        export const { NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD } =
          envSchema.parse(process.env);
        export const neo4jDriver = neo4j.driver(
          NEO4J_URI,
          neo4j.auth.basic(NEO4J_USERNAME, NEO4J_PASSWORD)
        );

        const typedefPath = path.join(RootDir, "src/graphql/schema.gql");
        export const typeDefs = fs.readFileSync(typedefPath).toString();

        const neoSchema = new Neo4jGraphQL({
          typeDefs: typeDefs,
          driver: neo4jDriver,
          resolvers: authResolvers, // custom resolvers must be added to Neo4jGraphQL instead of providers list of NestJS module
          features: {
            authorization: {
              key: "huakun",
            },
          },
        });

        const schema = await neoSchema.getSchema();
        return {
          schema,
          plugins: [ApolloServerPluginLandingPageLocalDefault()],
          playground: false,
          context: ({ req }) => ({
            token: req.headers.authorization,
          }),
        };
      },
    }),
  ],
  providers: [],
})
export class GraphqlModule {}

The resolver must be provided to Neo4jGraphQL constructor. It must be an object, so NestJS's class-based resolver won't work.

You must provide regular apollo stype resolvers. See https://neo4j.com/docs/graphql/current/ogm/installation/ for similar example.

export const authResolvers = {
  Mutation: {
    signUp: async (_source, { username, password }) => {
      ...
      return createJWT({ sub: users[0].id });
    },
    signIn: async (_source, { username, password }) => {
      ...
      return createJWT({ sub: user.id });
    },
  },
};

Read the README.md of this repo for more details. Run the code and read the source code to understand how it works. It's a minimal example.

Codegen

https://the-guild.dev/graphql/codegen is used to generate TypeScript types and more from the GraphQL schema.

Usually you provide the graphql schema file, but in this demo, the schema is designed for neo4j and not recognized by the codegen tool.

You need to let Neo4jGraphQL generate the schema and deploy it to a server first, then provide the server's endpoint to the codegen tool.
Then the codegen tool will introspect the schema from the server and generate the types.

Make sure the server is running before running codegen

cd packages/codegen
pnpm codegen

The generated files are in the packages/codegen/src/gql folder.

Sample operations can be added to packages/codegen/operations. Types and caller for operations will also be generated.

Read the documentation of codegen for more details.

Examples is always provided in the packages/codegen folder.

This is roughly how the generated code it works:

You get full type safety when calling the operations. The operations documents are predefined in a central place rather than in the code. This is useful when you have a large project with many operations. Modifying one operation will update all the callers. And if the type is no longer valid, the compiler will tell you.

The input variables are also protected by TypeScript. You won't need to guess what the input variables are. The compiler will tell you.

import { CreateMoviesDocument } from "./src/gql/graphql";

async function main() {
  const client = new ApolloClient({
    uri: "http://localhost:3000/graphql",
    cache: new InMemoryCache(),
  });
  client
    .mutate({
      mutation: CreateMoviesDocument,
      variables: {
        input: [
          {
            actors: {
              create: [
                {
                  node: {
                    name: "jacky",
                  },
                },
              ],
            },
            title: "fallout",
          },
        ],
      },
    })
    .then((res) => {
      console.log(res);
    });
}

Rust SocketIO Event Handling with Channel (rust-socketio)

Huakun Shen — Thu, 13 Mar 2025 04:03:53 +0000

rust-socketio is an open source Rust client for socket.io

It has an async version, but the event handling is a bit tricky. All callback functions (closures) have to use async move {} to handle events. To use variables outside the closure, you have to make clones of the variables and pass them to the closure. The regular sync version also needs to do this, but the async version is more complicated because of the async nature. The variables have to be cloned and moved twice.

#[tokio::main]
async fn main() {
    let (tx, rx) = channel::<String>();
    let tx2 = tx.clone();
    let socket = ClientBuilder::new("http://localhost:9559")
        .on("evt1", move |payload, socket| {
            let tx = tx.clone();
            async move {
                tx.send(format!("identity: {:?}", payload)).unwrap();
            }
            .boxed()
        })
        // .on("evt1", callback2)
        .on_any(move |evt, payload, socket| {
            let tx = tx2.clone();
            async move {
                tx.send(format!("{:?}", payload)).unwrap();
            }
            .boxed()
        })
        .connect()
        .await
        .expect("Connection failed");
}

This makes things complicated and hard to read. I have to clone variables so many times. Rust's nature keeps me focusing on the language itself rather than the business logic. In JS I could finish this without even thinking about this problem.

See this issue https://github.com/1c3t3a/rust-socketio/issues/425

Solution

What I ended up doing is use on_any and channel to transfer all event handling to another loop outside the closures to avoid variables moving. It's much simpler.

Here is how I did it.

#[derive(Debug)]
pub struct EventMessage {
    pub event: String,
    pub payload: Payload,
}

let (done_tx, mut done_rx) = tokio::sync::mpsc::channel::<()>(1);
let (evt_tx, mut evt_rx) = tokio::sync::mpsc::channel::<EventMessage>(1);

let socket = ClientBuilder::new(SERVER_URL)
    .on(Event::Connect, |_, _| async move {}.boxed())
    .on_any(move |evt, payload, _| {
        let evt_tx = evt_tx.clone();
        async move {
            evt_tx
                .send(EventMessage {
                    event: evt.to_string(),
                    payload,
                })
                .await
                .unwrap();
        }
        .boxed()
    })
    .on(Event::Error, |err, _: Client| {
        async move {
            eprintln!("Error: {:#?}", err);
        }
        .boxed()
    })
    .connect()
    .await
    .expect("Connection failed");


loop {
    tokio::select! {
        _ = done_rx.recv() => {
            break;
        }
        Some(evt) = evt_rx.recv() => {
            // Handle event received from evt_rx
            match evt.event.as_str() {
                "evt1" => {...}
                "evt2" => {...}
            }
        }
        _ = tokio::signal::ctrl_c() => {
            break;
        }
    };
}

All events are caught by on_any and sent to evt_tx. Then I can handle all events in the loop outside the closures. This way I don't have to clone variables so many times and move them. It's much simpler and easier to read.

Not sure about the performance difference. It shouldn't matter as this is dealing with network I/O. The performance bottleneck is the network, not the CPU. So I think this is a good solution.

Cloning variables, locking and unlocking mutexes, and moving variables from stack to heap all cost time, and are harder to read. Unsure about the cost of using channels, but I think it's a good trade-off.

I am thinking about a new design for rust_socketio. The ClientBuilder can simply return a channel to the user, and the user can handle all events in the loop with select outside the closures. This way the user can handle events in a more natural way.

Asymmetric Encryption and TLS in Rust

Huakun Shen — Thu, 13 Mar 2025 04:03:03 +0000

In this article, I will briefly discuss application of Asymmetric Encryption (ed25519) and TLS in Rust.

SSL/TLS uses asymmetric encryption during the handshake phase to exchange keys securely and ensure authenticity.
Asymmetric encryption ensures that communication is secure by using public-private key pairs. Algorithms like RSA, ECDSA, or ed25519 are used to verify identities and sometimes exchange keys.
ed25519 is a specific algorithm used primarily for signing in asymmetric cryptography, providing a fast and secure way to verify that data (or certificates) are from a trusted source.

Data Signing

Signing Data with ed25519

ed25519 is often used for SSH authentication. You store the public key on the server, and the private key on the client.
Then you can ssh to server with the client private key, without the need to enter password.

SSH (Secure Shell) uses ed25519 keys for authentication in the following way:

Key Generation: The user generates an ed25519 key pair. The private key is kept securely on the client machine, while the public key is placed on the server.
Connection Initiation: When a client attempts to connect to an SSH server, the server sends a challenge to the client.
Signing the Challenge: The client uses its private key to sign the challenge, creating a signature.
Signature Verification: The client sends this signature back to the server. The server then uses the stored public key to verify the signature.
Authentication: If the signature is valid, it proves that the client possesses the corresponding private key, and the server grants access.

This process ensures secure authentication without transmitting the private key, leveraging the strength and efficiency of the ed25519 algorithm.

Let's use the popular ed25519 algorithm, which is usually used for ssh keys.

use ring::rand::SystemRandom;
use ring::signature::{Ed25519KeyPair, KeyPair, Signature, UnparsedPublicKey, ED25519};

fn main() {
    // Generate key pair
    let rng = SystemRandom::new();
    let private_key = Ed25519KeyPair::generate_pkcs8(&rng).unwrap();
    let key_pair = Ed25519KeyPair::from_pkcs8(private_key.as_ref()).unwrap();

    // Data to sign
    let message = b"Hello, sign this data!";

    // Sign the message
    let signature: Signature = key_pair.sign(message);

    // Verify the signature using the public key
    let public_key = key_pair.public_key();
    let peer_public_key_bytes = public_key.as_ref();

    let public_key_for_verification = UnparsedPublicKey::new(&ED25519, peer_public_key_bytes);
    match public_key_for_verification.verify(message, signature.as_ref()) {
        Ok(_) => println!("Signature verified successfully!"),
        Err(_) => println!("Signature verification failed!"),
    }
}

RSA Encryption

Asymmetric encryption is used for public key encryption, where the public key is used to encrypt data, and the private key is used to decrypt data.

ed25519 is not used for public key encryption, but RSA is.

use rsa::{Pkcs1v15Encrypt, RsaPrivateKey, RsaPublicKey};

fn main() {
    let mut rng = rand::thread_rng();
    let bits = 2048;
    let priv_key = RsaPrivateKey::new(&mut rng, bits).expect("failed to generate a key");
    let pub_key = RsaPublicKey::from(&priv_key);

    // Encrypt
    let data = b"hello world";
    let enc_data = pub_key
        .encrypt(&mut rng, Pkcs1v15Encrypt, &data[..])
        .expect("failed to encrypt");
    assert_ne!(&data[..], &enc_data[..]);

    // Decrypt
    let dec_data = priv_key
        .decrypt(Pkcs1v15Encrypt, &enc_data)
        .expect("failed to decrypt");
    assert_eq!(&data[..], &dec_data[..]);
}

SSL Certificate for HTTPS Server

TLS/SSL is more complicated, it involves asymmetric encryption, symmetric encryption, hash functions, and more.

Here we only show how to use a self-signed certificate for local use.

Let's generate a self-signed certificate and serve with an Axum rust server. Self-signed certificate is usually used in local network, between devices, but require some level of security.

Generate SSL Certificate

// rcgen = "0.13.1"
use rcgen::generate_simple_self_signed;
use std::fs::File;
use std::io::Write;
use std::path::PathBuf;

fn main() {
    let subject_alt_names = vec!["localhost".to_string()];
    let cert_key = generate_simple_self_signed(subject_alt_names).unwrap();
    let cert = cert_key.cert;
    let key = cert_key.key_pair;
    println!("Certificate generated successfully");
    let pem = cert.pem();
    let key = key.serialize_pem();

    println!("{}", pem);
    println!("{}", key);
    let pem_path = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("cert.pem");
    let key_path = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("key.pem");

    let mut pem_file = File::create(pem_path).unwrap();
    let mut key_file = File::create(key_path).unwrap();

    pem_file.write_all(pem.as_bytes()).unwrap();
    key_file.write_all(key.as_bytes()).unwrap();
}

Simple Server with TLS

use axum::{routing::get, Router};
use axum_server::tls_rustls::RustlsConfig;
use std::{net::SocketAddr, path::PathBuf};

#[tokio::main]
async fn main() {
    let https_port = 8080;
    rustls::crypto::ring::default_provider()
        .install_default()
        .expect("Failed to install default CryptoProvider");
    let handle = axum_server::Handle::new();
    let config = RustlsConfig::from_pem_file(
        PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("cert.pem"),
        PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("key.pem"),
    )
    .await
    .unwrap();
    let app = Router::new().route("/", get(handler));
    let addr = SocketAddr::from(([127, 0, 0, 1], https_port));
    tracing::debug!("listening on {addr}");
    axum_server::bind_rustls(addr, config)
        .handle(handle)
        .serve(app.into_make_service())
        .await
        .unwrap();
}

async fn handler() -> &'static str {
    "Hello, World!"
}

For full examples with http redirect and graceful shutdown, go to Axum's GitHub repo which contains TLS examples.

Query HTTPS

To query a https server with self-signed cert, you would usually get errors.

To do it in Rust with reqwest, set .danger_accept_invalid_certs(true).

use reqwest::Client;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a custom client
    let client = Client::builder()
        .danger_accept_invalid_certs(true)
        .build()?;

    // Make the request
    let response = client
        .get("https://localhost:3000")
        .send()
        .await?;

    println!("Status: {}", response.status());
    println!("Body: {}", response.text().await?);

    Ok(())
}

In Node.js and Bun, need to set environment variable NODE_TLS_REJECT_UNAUTHORIZED=0, but this will disable security check for entire program, not just a single request.

Build Svelte AI Chat with Vercel's AI sdk

Huakun Shen — Thu, 13 Mar 2025 04:01:43 +0000

Chat apps are very popular since ChatGPT got viral, and so many tools were created for building Chat apps, e.g. langchain.

However, almost all AI chat apps I've seen are created with React.
Svelte is my favourite and what I used to create Kunkun, and I have to implement a AI chat app with svelte.

Dependencies

Vercel's AI sdk
- For svelte: https://sdk.vercel.ai/docs/getting-started/svelte
- Vercel's AI sdk is very powerful with many features, and most importantly, supports svelte.
svelte-exmarkdown
- svelte-exmarkdown is extensible, supports rehype and remark plugins, and also custom renderer.
- Without these features, I won't be able to create code highlight, latex, or copy button on code blocks.
- Docs

Markdown Component

```svelte title="Markdown.svelte"

import rehypeShikiFromHighlighter from "@shikijs/rehype/core" import rehypeClassNames from "rehype-class-names" import rehypeKatex from "rehype-katex" import remarkMath from "remark-math" import { createHighlighterCoreSync } from "shiki/core" import { createJavaScriptRegexEngine } from "shiki/engine/javascript" import svelte from "shiki/langs/svelte.mjs" import ts from "shiki/langs/typescript.mjs" import githubDarkDefault from "shiki/themes/github-dark-default.mjs" import Markdown from "svelte-exmarkdown" import type { Plugin } from "svelte-exmarkdown" import Pre from "./Pre.svelte" const addClass: Plugin = { rehypePlugin: [ rehypeClassNames, { pre: "p-4 rounded-md overflow-auto" } ] } const shikiPlugin = { rehypePlugin: [ rehypeShikiFromHighlighter, createHighlighterCoreSync({ themes: [githubDarkDefault], langs: [ ts, svelte, ], engine: createJavaScriptRegexEngine() }), { theme: "github-dark-default" } ] } satisfies Plugin const plugins: Plugin[] = [ shikiPlugin, { remarkPlugin: [remarkMath], rehypePlugin: [rehypeKatex] }, addClass, { renderer: { pre: Pre } } ] let { md }: { md: string } = $props()




The `pre` custom renderer is optional. I used a custom `pre` renderer to add a copy button.



```svelte title="Pre.svelte"
<script lang="ts">
    import { Button } from '@kksh/svelte5';
    import { CopyIcon } from 'lucide-svelte';
    import type { Snippet } from 'svelte';

    let pre: HTMLPreElement;

    let {
        children,
        class: className,
        style
    }: { children: Snippet; class?: string; style?: string } = $props();
</script>

<div class="relative">
    <pre class={className} {style} bind:this={pre}>{@render children()}</pre>
    <Button
        size="icon"
        variant="outline"
        onclick={() => navigator.clipboard.writeText(pre.textContent ?? '')}
        class="absolute right-2 top-2"
    >
        <CopyIcon />
    </Button>
</div>

Server

https://sdk.vercel.ai/docs/getting-started/svelte contains example to create server with ai sdk with SvelteKit server routes.

However, I prefer using a separate server for this. My current favourite server framework is Hono.

See https://sdk.vercel.ai/cookbook/api-servers/hono#hono for AI Sdk's Hono sample code.

Sample Hono Code ```ts title="server.ts" import { openai } from "@ai-sdk/openai"; import { serve } from "@hono/node-server"; import { streamText } from "ai"; import { Hono } from "hono"; import { stream } from "hono/streaming"; const app = new Hono(); app.post("/", async (c) => { const result = streamText({ model: openai("gpt-4o"), prompt: "Invent a new holiday and describe its traditions.", }); // Mark the response as a v1 data stream: c.header("X-Vercel-AI-Data-Stream", "v1"); c.header("Content-Type", "text/plain; charset=utf-8"); return stream(c, (stream) => stream.pipe(result.toDataStream())); }); serve({ fetch: app.fetch, port: 8080 }); ```

Chat Page

The SERVER_URL_URL constant is the url to the server. https://<domain>/api/chat.

```svelte title="chat/+page.svelte"

import { SERVER_URL_URL } from '@/constants';
import { useChat } from '@ai-sdk/svelte';
import { Markdown } from '@kksh/ui/markdown';
import { Button, Textarea, Card, Input, Badge } from '@kksh/svelte5';
import { ScrollArea } from '@kksh/ui';
import { IconMultiplexer } from '@kksh/ui';
import { IconEnum } from '@kksh/api/models';
import { GlobeIcon } from 'lucide-svelte';
import sampleMessages from './sample-messages.json';
import 'katex/dist/katex.min.css';
import { onMount } from 'svelte';
import Inspect from 'svelte-inspect-value';
import { dev } from '$app/environment';
import { preferences } from '@/stores/preference';
import { fade } from 'svelte/transition';
import { type UIMessage } from 'ai';

const { data } = $props();
let usage = $state&lt;{
    completionTokens: number;
    promptTokens: number;
    totalTokens: number;
}&gt;({
    completionTokens: 0,
    promptTokens: 0,
    totalTokens: 0
});
const { input, handleSubmit, messages, setMessages } = useChat({
    api: SERVER_URL_URL,
    headers: {
        Authorization: `Bearer ${data.session?.access_token}`
    },
    onResponse: (response) =&gt; {
        console.log(response.headers);
    },
    onFinish: (msg, options) =&gt; {
        console.log('finished', msg, options);
        usage = options.usage;
    }
});

let messagesContainer: HTMLDivElement | null = $state(null);

$effect(() =&gt; {
    if ($messages.length &gt; 0) {
        scrollToBottom();
    }
});

onMount(() =&gt; {
    scrollToBottom();
    if (dev) {
        setMessages(sampleMessages as unknown as UIMessage[]);
    }
});

const scrollToBottom = () =&gt; {
    if (messagesContainer) {
        messagesContainer.scrollTo({
            top: messagesContainer.scrollHeight,
            behavior: 'smooth'
        });
    }
};

const handleKeyDown = (event: KeyboardEvent) =&gt; {
    // Handle Ctrl+K to clear messages
    if (event.key === 'k' &amp;&amp; (event.ctrlKey || event.metaKey)) {
        event.preventDefault();
        setMessages([]);
        $input = '';
        return;
    }

    // Handle Enter for submission (but not with Shift)
    if (event.key === 'Enter' &amp;&amp; !event.shiftKey) {
        event.preventDefault();
        handleSubmit(event);
    }
};

/* -------------------------------------------------------------------------- */
/*                               Textarea Expand                              */
/* -------------------------------------------------------------------------- */
let textareaEl: HTMLTextAreaElement | null = $state(null);

const autoResize = (textarea: HTMLTextAreaElement) =&gt; {
    textarea.style.height = 'auto';
    const newHeight = Math.min(textarea.scrollHeight, 10 * 24); // Assuming ~24px per row
    textarea.style.height = newHeight + 'px';
};

const handleInput = (event: Event) =&gt; {
    const textarea = event.target as HTMLTextAreaElement;
    autoResize(textarea);
};

{#snippet usageDisplay()}

Tokens used: {usage.totalTokens}

Prompt tokens: {usage.promptTokens}

Completion tokens: {usage.completionTokens}

{/snippet} {#if $preferences.developerMode} {/if} {#each $messages as message} {#if message.role === 'user'}

{message.content}

        {:else}

                {message.role}


        {/if}
    {/each}








                    <span>Search</span>





            {@render usageDisplay()}

Magic Wormhole Source Code Analysis

Huakun Shen — Thu, 13 Mar 2025 03:59:08 +0000

Clients

Python: https://github.com/magic-wormhole/magic-wormhole (official, original)
Rust: https://github.com/magic-wormhole/magic-wormhole.rs (official)
Golang: https://github.com/psanford/wormhole-william.git (non-official)
Golang + Fyne GUI Client: https://github.com/Jacalz/rymdport
Rust + Tauri GUI Client: https://github.com/HuakunShen/wormhole-gui

Documentation

Performance

magic-wormhole can almost always eat the full bandwidth of the network. It's very fast. However, I have observed performance issue on Mac (M1 pro) during sending (not receiving).

See update on issue https://github.com/magic-wormhole/magic-wormhole.rs/issues/224

Sender Computer	Sender Client	Receiver Computer	Receiver Client	Speed
M1 pro Mac	python	Ubuntu i7 13700K	python	112MB/s
M1 pro Mac	rust	Ubuntu i7 13700K	python	73MB/s
M1 pro Mac	golang	Ubuntu i7 13700K	python	117MB/s
Ubuntu i7 13700K	python	M1 pro Mac	python	115MB/s
Ubuntu i7 13700K	rust	M1 pro Mac	python	116MB/s
Ubuntu i7 13700K	golang	M1 pro Mac	python	117MB/s
Ubuntu i7 13700K	python	Kali VM (on Mac)	python	119MB/s
Kali VM (on Mac)	python	Ubuntu i7 13700K	python	30MB/s
Ubuntu i7 11800H	rust	Ubuntu i7 13700K	python	116MB/s
Ubuntu i7 13700K	rust	Ubuntu i7 11800H	python	116MB/s

It seems like there is some performance issue with the rust implementation on the sender side.

Workflow

I read the client source code written in Python, Golang and Rust. The Python code is unreadable to me. Some packages like automat and twisted are used. I am not familiar with them and they make the code hard to read or follow. It even took me ~20-30 minutes to find the main function and get the debugger running. The code is not well-organized. It's hard to follow the workflow.

Rust is known for its complexity. It's async and await makes debugger jump everywhere. Variables allocated in heap are hard to track with debugger. Usually only a pointer address is shown.

The Golang version (although non-official) is the easiest to follow. Project structure is clear and simple. Goland's debugger works well. So let's follow the Golang version.

After command arguments parsing, everything starts here sendFile(args[0])
A wormhole.Client is created c := newClient()
The code is retrieved from code, status, err := c.SendFile(ctx, filepath.Base(filename), f, args...)

- status is a channel (var status chan wormhole.SendResult) that waits for the result of sending file.
```
    s := <-status

    if s.OK {
        fmt.Println("file sent")
    } else {
        bail("Send error: %s", s.Error)
    }
```

Here is Wormhole Client's `SendFile()` method

    func (c *Client) SendFile(ctx context.Context, fileName string, r io.ReadSeeker, opts ...SendOption) (string, chan SendResult, error) {
        if err := c.validateRelayAddr(); err != nil {
            return "", nil, fmt.Errorf("invalid TransitRelayAddress: %s", err)
        }

        size, err := readSeekerSize(r)
        if err != nil {
            return "", nil, err
        }

        offer := &offerMsg{
            File: &offerFile{
                FileName: fileName,
                FileSize: size,
            },
        }

        return c.sendFileDirectory(ctx, offer, r, opts...)
    }

offer contains the file name and size.

Let's go into sendFileDirectory() method here. Everything happens here.

sideId: RandSideID returns a string appropate for use as the Side ID for a client.

NewClient returns a Rendezvous client. URL is the websocket url of Rendezvous server. SideID is the id for the client to use to distinguish messages in a mailbox from the other client. AppID is the application identity string of the client.

Two clients can only communicate if they have the same AppID.

sideID := crypto.RandSideID()
appID := c.appID()
rc := rendezvous.NewClient(c.url(), sideID, appID)

_, err := rc.Connect(ctx)

Then a nameplate is generated

If users provides the code, the mailbox is attached to the code. Otherwise, a new mailbox is created. A mailbox is a channel for communication between two clients. The sender creates a mailbox and sends the code (address of mailbox + key) to the receiver. The receiver uses the code to open the mailbox.

if options.code == "" {
  // CreateMailbox allocates a nameplate, claims it, and then opens the associated mailbox. It returns the nameplate id string.
  // nameplate is a number string. e.g. 10
  nameplate, err := rc.CreateMailbox(ctx)
  if err != nil {
    return "", nil, err
  }

  // ChooseWords returns 2 words from the wordlist. (e.g. "correct-horse")
  pwStr = nameplate + "-" + wordlist.ChooseWords(c.wordCount())
} else {
  pwStr = options.code
  nameplate, err := nameplateFromCode(pwStr)
  if err != nil {
    return "", nil, err
  }

  // AttachMailbox opens an existing mailbox and releases the associated nameplate.
  err = rc.AttachMailbox(ctx, nameplate)
  if err != nil {
    return "", nil, err
  }
}

Then a clientProto is created

  clientProto := newClientProtocol(ctx, rc, sideID, appID)

appID is a constant string. sideID is a random string.

sideID := crypto.RandSideID() RandSideID returns a string appropate for use as the Side ID for a client.

Let's see how newClientProtocol works.

  type clientProtocol struct {
    sharedKey    []byte
    phaseCounter int
    ch           <-chan rendezvous.MailboxEvent
    rc           *rendezvous.Client
    spake        *gospake2.SPAKE2
    sideID       string
    appID        string
  }

  func newClientProtocol(ctx context.Context, rc *rendezvous.Client, sideID, appID string) *clientProtocol {
    recvChan := rc.MsgChan(ctx)

    return &clientProtocol{
      ch:     recvChan,
      rc:     rc,
      sideID: sideID,
      appID:  appID,
    }
  }

Then enter a go routing (transfer happens here)
clinetProto.ReadPake(ctx): block and waiting for receiver to connect (wait for receiver to enter the code)

ReadPake calls readPlainText to read the event from the mailbox.

  func (cc *clientProtocol) readPlaintext(ctx context.Context, phase string, v interface{}) error {
    var gotMsg rendezvous.MailboxEvent
    select {
    case gotMsg = <-cc.ch:
    case <-ctx.Done():
      return ctx.Err()
    }
    if gotMsg.Error != nil {
      return gotMsg.Error
    }

    if gotMsg.Phase != phase {
      return fmt.Errorf("got unexpected phase while waiting for %s: %s", phase, gotMsg.Phase)
    }

    err := jsonHexUnmarshal(gotMsg.Body, &v)
    if err != nil {
      return err
    }

    return nil
  }

  func (cc *clientProtocol) ReadPake(ctx context.Context) error {
    var pake pakeMsg
    err := cc.readPlaintext(ctx, "pake", &pake)
    if err != nil {
      return err
    }

    otherSidesMsg, err := hex.DecodeString(pake.Body)
    if err != nil {
      return err
    }

    sharedKey, err := cc.spake.Finish(otherSidesMsg)
    if err != nil {
      return err
    }

    cc.sharedKey = sharedKey

    return nil
  }

pake's body is a string of length 66. otherSidesMsg is []uint8 bytes of length 33.

Then sharedKey is generated by calling cc.spake.Finish(otherSidesMsg). spake is a SPAKE2 object.

sharedKey is a 32-byte long byte array.

So what is pake message read from the mailbox?

TODO

err = collector.waitFor(&answer): Wait for receiver to enter Y to confirm. The answer contains a OK message
A cryptor (type=transportCryptor) is created.

    cryptor := newTransportCryptor(conn, transitKey, "transit_record_receiver_key", "transit_record_sender_key")

    recordSize := (1 << 14) // record size: 16384 byte (16kb)
    // chunk
    recordSlice := make([]byte, recordSize-secretbox.Overhead)
    hasher := sha256.New()

conn is a net.TCPConn TCP connection.

A readKey and writeKey are generated with hkdf (HMAC-based Extract-and-Expand Key Derivation Function) from transitKey and two strings in newTransportCryptor.

transitKey is derived from clientProto.sharedKey and appID.

  transitKey := deriveTransitKey(clientProto.sharedKey, appID)

sharedKey is a 32-byte long key generated by clientProto (a pake.Client).

  func newTransportCryptor(c net.Conn, transitKey []byte, readPurpose, writePurpose string) *transportCryptor {
    r := hkdf.New(sha256.New, transitKey, nil, []byte(readPurpose))
    var readKey [32]byte
    _, err := io.ReadFull(r, readKey[:])
    if err != nil {
      panic(err)
    }

    r = hkdf.New(sha256.New, transitKey, nil, []byte(writePurpose))
    var writeKey [32]byte
    _, err = io.ReadFull(r, writeKey[:])
    if err != nil {
      panic(err)
    }

    return &transportCryptor{
      conn:          c,
      prefixBuf:     make([]byte, 4+crypto.NonceSize),
      nextReadNonce: big.NewInt(0),
      readKey:       readKey,
      writeKey:      writeKey,
    }
  }

recordSize is 16384 byte (16kb), used to read file in chunks.

hasher is compute file hash while reading file.

In the following loop, file is read and sent in chunks.

r has type io.Reader. Every time 16KB is read.

cryptor.writeRecord encrypts the bytes and send the bytes.

  for {
    n, err := r.Read(recordSlice)
    if n > 0 {
      hasher.Write(recordSlice[:n])
      err = cryptor.writeRecord(recordSlice[:n]) // send 16KB in each iteration
      if err != nil {
        sendErr(err)
        return
      }
      progress += int64(n)
      if options.progressFunc != nil {
        options.progressFunc(progress, totalSize)
      }
    }
    if err == io.EOF {
      break
    } else if err != nil {
      sendErr(err)
      return
    }
  }

Let's see how writeRecord works.

package secretbox ("golang.org/x/crypto/nacl/secretbox") is used to encrypt data.

d.conn.Write sends the encrypted data out.

  func (d *transportCryptor) writeRecord(msg []byte) error {
    var nonce [crypto.NonceSize]byte

    if d.nextWriteNonce == math.MaxUint64 {
      panic("Nonce exhaustion")
    }

    binary.BigEndian.PutUint64(nonce[crypto.NonceSize-8:], d.nextWriteNonce)
    d.nextWriteNonce++

    sealedMsg := secretbox.Seal(nil, msg, &nonce, &d.writeKey)

    nonceAndSealedMsg := append(nonce[:], sealedMsg...)

    // we do an explit cast to int64 to avoid compilation failures
    // for 32bit systems.
    nonceAndSealedMsgSize := int64(len(nonceAndSealedMsg))

    if nonceAndSealedMsgSize >= math.MaxUint32 {
      panic(fmt.Sprintf("writeRecord too large: %d", len(nonceAndSealedMsg)))
    }

    l := make([]byte, 4)
    binary.BigEndian.PutUint32(l, uint32(len(nonceAndSealedMsg)))

    lenNonceAndSealedMsg := append(l, nonceAndSealedMsg...)

    _, err := d.conn.Write(lenNonceAndSealedMsg)
    return err
  }

Svelte Command List Filtering with Virtual List and fuse.js

Huakun Shen — Thu, 13 Mar 2025 03:56:55 +0000

Background

I am using shadcn-svelte's Command component in my project Kunkun.

It is using Bits UI's Command component under the hood.

It's used to render Kunkun's command list and template UI extension's list view.

Problem

It may need to render hundreds of commands or list items, and I got performance problem.

Initial load is so slow when there are thousands of list items to render.
Every time I clear search term there is also a huge delay because it needs to render the entire list.

Bits UI's Command component's built-in filtering method is also too limited. Its value is a string, and default filtering is on the value. There is also custom filtering option, I can provide a filter function, but still it's hard to implement a advanced filtering on multiple fields of list item object. For example, I need to filter on title, subtitle, and keywords field. It is still possible. I have to construct a value to object map Record<String, Item>. Then in the filter function, obtain the original object with value and run filter score function on it.

function customFilter(
    commandValue: string,
    search: string,
    commandKeywords?: string[]
): number {
    const obj = dict[commandValue]

    const score = ... // run scoring algo
    return score
}

This becomes more complicated, and why don't I use an existing solution like fuse.js?

Solution

Use fuse.js for filtering (support multi-fields)
Use TanStack Virtual to render the list
- Even when there are thousands of list items, only ~30 will be rendered on the list

This solution should be very simple, just follow TanStack Virtual's example code in docs.

One problem I had was TanStack virtual assumes there is a single array of items to render, but I need to support sections and items. Sections contains items. TanStack Virtual doesn't provide an example to deal with this kind of nested structure.

My solution is to render sections and items in the same list <div/>. Use a separate virtualizer for each section. When items in each section are listed one by one via #each, they are listed by the virtualizer, so virtualizer can decide whether to really render them based on whether they are really in viewport (this is controlled by scrollMargin.

The position of each item are controlled with translateY style property, and calculated based on scrollMargin. For example, section 1's scrollMargin is 0, and if the height of section 1 is 100px, then the scrollMargin for section 2 becomes 100.

Code

// utils.ts this file contains types and functions for genering dummy data
import { faker } from "@faker-js/faker";

export function generateId() {
  return Math.random().toString(36).substring(2, 15);
}

export type Item = {
  id: string;
  name: string;
  description: string;
};

export type Section = {
  name: string;
  items: Item[];
  sectionRef: HTMLDivElement | null;
  sectionHeight: number;
};

export function getItems(n: number = 10): Item[] {
  return Array.from({ length: n }, () => ({
    id: generateId(),
    name: faker.person.fullName(),
    description: faker.lorem.sentence(),
  }));
}

export function getSections(n: number = 10): Section[] {
  return Array.from({ length: n }, () => ({
    name: faker.lorem.word(),
    items: getItems(3),
    sectionRef: null,
    sectionHeight: 0,
  }));
}

shouldFilter is set to false in Command.Root.

All the filtering are done with fuse.js and svelte runes. When searchTerm or list items change, fuse.search is run to update resultingItems.

<!-- +page.svelte -->
<script lang="ts">
    import { getSections, getItems } from "./utils.js"
    import * as Command from "$lib/components/ui/command/index.ts"
    import { createVirtualizer, type VirtualItem } from "@tanstack/svelte-virtual"
    import VirtualGroup from "./VirtualGroup.svelte"
    import Fuse from "fuse.js"
    import { setContext } from "svelte"

    const itemHeight = 30
    setContext("itemHeight", itemHeight)

    const sections = $state(getSections(1))
    const items = getItems(1000)
    let searchTerm = $state("")
    let virtualListEl: HTMLDivElement | null = $state(null)
    const fuse = new Fuse(items, {
        includeScore: true,
        threshold: 0.2,
        keys: ["name"]
    })
    let resultingItems = $derived(
        // when search term changes, update the resulting items
        searchTerm.length > 0 ? fuse.search(searchTerm).map((item) => item.item) : items
    )

    // section total height is auto derived from section refs
    let sectionTotalHeight = $derived(sections.reduce((acc, s) => acc + (s.sectionHeight ?? 0), 0))
    // this should be a list of numbers, the first item is 0, the second item equal to first sectionRef.clientHeight, and so on
    let sectionsCummulativeHeight = $derived(
        sections.map((s, i) => sections.slice(0, i).reduce((acc, s) => acc + (s.sectionHeight ?? 0), 0))
    )

    let virtualizer = createVirtualizer<HTMLDivElement, HTMLDivElement>({
        count: items.length,
        getScrollElement: () => virtualListEl,
        estimateSize: () => itemHeight,
        overscan: 5
    })

    let virtualItems: VirtualItem[] = $state([])
    let itemsTotalSize = $state(0)

    $effect(() => {
        void resultingItems
        $virtualizer.setOptions({ count: resultingItems.length, scrollMargin: sectionTotalHeight })
        virtualItems = $virtualizer.getVirtualItems()
        itemsTotalSize = $virtualizer.getTotalSize()
    })
</script>

<Command.Root shouldFilter={false}>
    <Command.Input placeholder="Search..." bind:value={searchTerm} />
    <Command.List bind:ref={virtualListEl}>
        <div style="position: relative; height: {itemsTotalSize + sectionTotalHeight}px; width: 100%;">
            {#each sections as section, i}
                <VirtualGroup
                    heading={section.name}
                    items={section.items}
                    parentRef={virtualListEl}
                    bind:sectionRef={section.sectionRef}
                    scrollMargin={sectionsCummulativeHeight[i]}
                    bind:sectionHeight={section.sectionHeight}
                    {searchTerm}
                />
            {/each}
            {#each virtualItems as row (row.index)}
                <Command.Item
                    style="position: absolute; top: 0; left: 0; width: 100%; height: {row.size}px; transform: translateY({row.start}px);"
                >
                    <span>{row.index}: {resultingItems[row.index]?.name}</span>
                </Command.Item>
            {/each}
        </div>
    </Command.List>
    <footer class="">hello</footer>
</Command.Root>

Each section has a sectionRef and sectionHeight field, and are bind to VirtualGroup, so when their height changes, sectionsCummulativeHeight and sectionTotalHeight are also updated with $derived.

Each value in sectionsCummulativeHeight array is the scrollMargin for each section (basically means how much space does your previous sections take).

Within each section/VirutalGroup, filtering is done again with fuse.js on items in the section.

<!-- VirtualGroup.svelte -->
<script lang="ts">
    import * as Command from "$lib/components/ui/command/index.ts"
    import type { Item } from "./utils.ts"
    import { getContext, onMount } from "svelte"
    import { createVirtualizer, type VirtualItem } from "@tanstack/svelte-virtual"
    import Fuse from "fuse.js"

    let {
        heading,
        items,
        parentRef,
        searchTerm,
        sectionHeight = $bindable(0),
        sectionRef = $bindable(null),
        scrollMargin = $bindable(0)
    }: {
        heading: string
        items: Item[]
        sectionHeight: number
        searchTerm: string
        parentRef: HTMLDivElement | null
        sectionRef: HTMLDivElement | null
        scrollMargin: number
    } = $props()

    const fuse = new Fuse(items, {
        includeScore: true,
        threshold: 0.2,
        keys: ["name"]
    })

    const itemHeight = getContext<number>("itemHeight") ?? 30

    let virtualizer = createVirtualizer<HTMLDivElement, HTMLDivElement>({
        count: items.length,
        getScrollElement: () => parentRef,
        estimateSize: () => itemHeight,
        overscan: 5
    })
    let virtualItems: VirtualItem[] = $state([])
    let itemsTotalSize = $state(0)

    let resultingItems = $derived(
        // when search term changes, update the resulting items
        searchTerm.length > 0 ? fuse.search(searchTerm).map((item) => item.item) : items
    )

    $effect(() => {
        // when props.items update, update the fuse collection
        fuse.setCollection(items)
    })

    $effect(() => {
        // when resultingItems changes, update virtualizer count and scrollMargin
        $virtualizer.setOptions({ count: resultingItems.length, scrollMargin })
        virtualItems = $virtualizer.getVirtualItems()
        itemsTotalSize = $virtualizer.getTotalSize()
    })
    $effect(() => {
        sectionHeight = itemsTotalSize + itemHeight
    })
</script>

<Command.Group
    heading={`${heading} (${items.length})`}
    bind:ref={sectionRef}
    class="relative"
    style="height: {sectionHeight}px;"
>
    {#each virtualItems as row (row.index)}
        <Command.Item
            style="position: absolute; top: 0; left: 0; width: 100%; height: {row.size}px; transform: translateY({row.start -
                scrollMargin + itemHeight}px);"
        >
            <span>{row.index}: {resultingItems[row.index]?.name}</span>
        </Command.Item>
    {/each}
</Command.Group>

kkRPC: TypeScript RPC for Web Worker, stdio, iframe, browser extension

Huakun Shen — Thu, 13 Mar 2025 03:52:04 +0000

Talk is cheap. Show me the code: https://github.com/kunkunsh/kkrpc

Documentation: https://docs.kkrpc.kunkun.sh/

What is kkrpc

kkrpc is a Remote Procedural Call protocol designed for TypeScript. Inspired by comlink and similar to tRPC.

A TypeScript-first RPC library that enables seamless bi-directional communication between processes. Call remote functions as if they were local, with full TypeScript type safety and autocompletion support.

JSR Package

NPM Pac kage

Documen tati on by JSR

Typedoc D oc umentation

For example, if you want to run a Deno process from a node.js process or bun process, instead of using argv or stdin, stdout, stderr to communicate, kkrpc can be used to call exposed functions defined in another process like if they were a local function, without worrying about argument parsing or validation.

This functionality is implemented through stdio, utilizing a JSON-RPC-like protocol that has been customized to support bi-directional communication and callback functions.

You might wonder why use IPC (Inter-Process Communication) when Deno, Bun, and Node.js are all running TypeScript. Why not simply import modules directly and operate within a single process? You’re absolutely right—in most cases, this isn’t necessary. This implementation is primarily a basic demonstration of what’s possible. The RPC (Remote Procedure Call) communication between these JavaScript/TypeScript runtimes is more of a side effect, as kkrpc was originally designed for other use cases.

To expand its versatility, I’ve also created adapters for various protocols, including HTTP, WebSocket, and postMessage. This allows kkrpc to be used in a wide range of environments, such as communication between iframes, the main thread, web workers, web servers, and browser extensions.

The full feature set can be implemented as long as a two-way communication channel exists, such as WebSocket. HTTP, on the other hand, is inherently passive—servers cannot actively push data to clients. As a result, the communication channel established over HTTP is not truly bidirectional. That said, I don’t recommend using kkrpc for HTTP anyway. It wasn’t designed with HTTP in mind, and there are far better alternatives like tRPC. HTTP support is more of a bonus feature, implemented with minimal effort by writing a simple adapter.

Diagrams created by Excalidraw.

Why Did I Create kkrpc?

This project was created for another bigger project Kunkun.

Kunkun uses iframe and web worker as sandboxed extension runtime. Kunkun is the host app like a docker engine and need to expose APIs for extensions (like containers) in sandboxes to call.

I started with basic wrapper functions around postMessage. Then I found it too time consuming to support hundreds of APIs.

Then I come across Comlink.

Comlink makes WebWorkers enjoyable. Comlink is a tiny library (1.1kB), that removes the mental barrier of thinking about postMessage and hides the fact that you are working with workers.

At a more abstract level it is an RPC implementation for postMessage and ES6 Proxies.

Comlink is designed for the main thread to call functions exposed in web worker (also supports iframe).

My use case is the other way, calling functions exposed in main thread from web worker/iframe, and Comlink allows that. So I started using Comlink to expose many APIs from main thread to extensions, and this is where problems begin.

In the main thread, I expose multiple API objects.

// main thread
expose({
  fs: {
    read(file: string) {},
    write(file: string, content: string) {},
    exists(file: string): boolean {},
  },
  clipboard: {
    readText: () => {},
    writeText: (text: string) => {},
  },
});

Extensions are expected to import API proxies in API package like this.

import { clipboard, fs, toast } from "@kksh/api/headless";

Each API has a separate API object. So I wrap each of them with Comlink.wrap(). Here is a rough demo of how code is written in the @kksh/api package.

import { windowEndpoint, wrap, type Remote } from "comlink";

export const clipboard = wrap(
  windowEndpoint(globalThis.parent)
) as unknown as IClipboard;
export const fs = wrap(
  windowEndpoint(globalThis.parent)
) as unknown as IClipboard;

This works in debug mode, and has different behavior in release mode.

Comlink will release the proxies created with wrap if they are not used any more. See Comlink.releaseProxy.

Every proxy created by Comlink has the [releaseProxy]() method. Calling it will detach the proxy and the exposed object from the message channel, allowing both ends to be garbage collected.

const proxy = Comlink.wrap(port);
// ... use the proxy ...
proxy[Comlink.releaseProxy]();

If the browser supports the WeakRef proposal, [releaseProxy]() will be called automatically when the proxy created by wrap() gets garbage collected.

In my case, I am building a desktop app with Tauri, which uses the WebKit and WebView browsers. When extensions haven't finished running, the proxy is released. If the proxy from the clipboard API is released, the expose side (main thread) is also released, meaning the fs APIs no longer work. I have over 10 APIs, and there's no way to ensure each extension uses all of them to prevent them from being released.

See issues (nobody is maintaining Comlink):

Then I switched to another design. Since wrap returns a proxy, I can set its type to whatever I want.

// @kksh/api
type API = {
  clipboard: Remote<IClipboard>; // inherit from tauri-api-adapter
  fs: Remote<IFs>; // customized for kunkun, add file search API on top of tauri-api-adapter's fs API
};
const _api = wrap(windowEndpoint(globalThis.parent)) as unknown as API;
export const { clipboard, fs } = _api;

This method works, but then I encountered a memory overflow error. I'm not sure if it was caused by Comlink or Nuxt.js. I couldn't figure it out after debugging for a while.

In Kunkun, I also want to support calling Deno scripts from extensions running in Web Workers and iframes so that features from Node.js packages can be used. Tauri has a shell API, but I had to implement a whole argument parser for a simple extension, and data passing was also complicated. I even tried base64 encoding request data and passing it to stdin, then decoding the base64 response data from stdout. This felt inefficient. So I created comlink-stdio, a library built from scratch but inspired by the proxy idea from Comlink. Tauri’s shell API supports stdio, allowing me to use the two-way communication channel with stdin and stdout. I didn’t even read Comlink’s source code when implementing it. I designed it based on how I imagined Comlink was implemented, but for stdio.

I also had a poor developer experience using Nuxt.js and switched to SvelteKit. Nuxt.js feels great at the beginning, but as the project grows, the experience worsens. One problem I had was auto import. It sounds good, but when an error occurred, I had no idea where it came from. I had to start a new project, copy code bit by bit, and find out what was causing the error. I did this so many times and finally decided that was enough.

After switching to SvelteKit, I also decided to stop using Comlink and build my own library, kkrpc. So kkrpc becomes the all-in-one library that can be used to communicate between extension and main thread and shell API with Deno process.

kkrpc is the successor of comlink-stdio. I already have experience with proxy-style RPC and want to support postMessage, so the name comlink-stdio is no longer suitable. That’s why is renamed.

It works similarly to Comlink, but don’t care about proxy release. It uses postMessage to send request like JSON-RPC.

Here is an example with Web Worker, both side can call add() function exposed on the other side with a single channel.

💡

Each end of the channel can expose different APIs, simply pass the 2 API
interfaces as generics to <code>RPCChannel</code>. The following example
shares the same API interface for both sides to keep the sample short.

// math.ts
export interface API {
  add: (a: number, b: number) => Promise<number>;
}

export const apiMethods: API = {
  add: async (a: number, b: number) => a + b,
};

// Main thread
import { RPCChannel, WorkerChildIO, type DestroyableIoInterface } from "kkrpc";

const worker = new Worker(
  new URL("./scripts/worker.ts", import.meta.url).href,
  { type: "module" }
);
const io = new WorkerChildIO(worker);
const rpc = new RPCChannel<API, API, DestroyableIoInterface>(io, {
  expose: apiMethods,
});
const api = rpc.getAPI();

expect(await api.add(1, 2)).toBe(3);

// web worker
import { RPCChannel, WorkerParentIO, type DestroyableIoInterface } from "kkrpc";

const io: DestroyableIoInterface = new WorkerChildIO();
const rpc = new RPCChannel<API, API, DestroyableIoInterface>(io, {
  expose: apiMethods,
});
const api = rpc.getAPI();

const sum = await api.add(1, 2);
expect(sum).toBe(3);

WorkerChildIO is the adapter, the same code can be reused with stdio, http, web socket, and browser extensions by swapping the adapter. An adapter is responsible for reading (receiving) and writing (sending) request/responses to the other side of the channel.

I also built an adapter for Tauri’s shell so extensions can use the shell API to call functions exposed from Deno process. This enables much more features for extensions.

Here is an http example in CodeSandox

Deep Dive

The message structure is different from JSON-RPC 2.0, but similar in concept.

Each message can serve as a request, response or callback. method is used to locate the exposed API.

interface Message<T = any> {
  id: string;
  method: string;
  args: T;
  type: "request" | "response" | "callback"; // Add "callback" type
  callbackIds?: string[]; // Add callbackIds field
}

Adapter

To make kkRPC work anywhere, IoInterface is introduced. It’s a common interface for any bidirectional communication channel.

interface IoInterface {
  name: string;
  read(): Promise<Buffer | Uint8Array | string | null>; // Reads input
  write(data: string): Promise<void>; // Writes output
}

name is only used for debugging.

Any environment that can establish a connection should be able to implement read and write function. read means reading data from the remote; write means writing data to the remote.

So as long as the environment can read and write, it can be used as a communication channel.

To adapt to a new environment, simply implement IoInterface on an adapter and pass it to RPCChannel.

RPCChannel does all the underlying magic, including serialization/deserialization, request-response matching, callback managing, proxy generating, etc.

Extend to Other Languages

JS/TS has the advantage of dynamic typing and super free syntax which allows proxy, eventually allowing calling remote RPC methods like if the are local with TypeScript support.

kkRPC was created for TypeScript projects, it doesn’t have a schema like GraphQL or gRPC’s .proto file. This project will be so complicated if I want to do that, code generate for other languages will be a ton of work and I don’t want to do that.

Since the underlying protocol is quite simple (similar to JSON-RPC), it’s possible to extend to other languages. Just implement the same IO interface and channel in the target language, it’s not too hard.

The problem is, you can’t reuse the API type/interface from TypeScript, and there is most likely no proxy support (you will need to write the method names). In this case, I don’t think kkRPC is a good choice, you lose all the benefits of kkRPC (i.e. proxy, TypeScript, intellisense).

If you are sure you need other languages for features like callback, then you can implement your own channel and IO adapter.

In a nutshell, if you are using TypeScript on both sides of the channel, kkrpc would be a very convenient choice.

Forem: Huakun Shen

Tauri Without Electron Bloat: A Type-Safe JS Runtime Bridge with `tauri-plugin-js`

Tauri Without Electron Bloat: A Type-Safe JS Runtime Bridge with tauri-plugin-js

The architecture in one sentence

Why this model works better than ad-hoc sidecar wiring

1) Lifecycle is first-class, not an afterthought

2) Stream transport has production-grade edge handling

3) Type-safe API remains shared across UI and workers

Runtime mode vs sidecar mode: practical deployment strategy

Runtime mode (great for dev)

Sidecar mode (great for distribution)

The Deno compile trap (and the clean workaround)

A small but smart DX trick: placeholder resources

Multi-window behavior is naturally supported

Code-level flow from click to typed result

What to copy into your own Tauri app

References

Repo sources

External docs (for production hardening)

Building a Local-First Tauri App with Drizzle ORM, Encryption, and Turso Sync (tauri-plugin-libsql)

Building a Local-First Tauri App with Drizzle ORM, Encryption, and Turso Sync

The Problem with Databases in Tauri

Why libsql

Making Drizzle Work in a WebView

Solving the Migration Problem

Encryption

Turso Embedded Replica

The Weird Bugs

Bug 1: The IPC That Never Responded

Bug 2: execute_batch Silently Failing with Embedded Replicas

Bug 3: The $state That Wasn't

Bug 4: Error State That Ate the Form

The Demo App

Installation

What's Next

drizzle + sqlite in Tauri App

Build a free ip info cache with PocketBase

Why Pocketbase?

Sample Response

NestJS + Neo4j + GraphQL Setup

GraphQL Schema

NestJS Server Configuration

GraphQL Module

Codegen

Rust SocketIO Event Handling with Channel (rust-socketio)

Solution

Asymmetric Encryption and TLS in Rust

Data Signing

Signing Data with ed25519

RSA Encryption

SSL Certificate for HTTPS Server

Generate SSL Certificate

Simple Server with TLS

Query HTTPS

Build Svelte AI Chat with Vercel's AI sdk

Dependencies

Markdown Component

Server

Chat Page

Magic Wormhole Source Code Analysis

Clients

Documentation

Performance

Workflow

- status is a channel (var status chan wormhole.SendResult) that waits for the result of sending file.

Here is Wormhole Client's SendFile() method

Svelte Command List Filtering with Virtual List and fuse.js

Background

Problem

Solution

Code

kkRPC: TypeScript RPC for Web Worker, stdio, iframe, browser extension

What is kkrpc

Why Did I Create kkrpc?

Deep Dive

Adapter

Extend to Other Languages

Tauri Without Electron Bloat: A Type-Safe JS Runtime Bridge with `tauri-plugin-js`

Bug 2: `execute_batch` Silently Failing with Embedded Replicas

Bug 3: The `$state` That Wasn't

- `status` is a channel (`var status chan wormhole.SendResult`) that waits for the result of sending file.

Here is Wormhole Client's `SendFile()` method