DEV Community: Ishan Naik

On-Device Computer Vision in React Native: Auto-Aligning Progress Photos with MediaPipe and Expo

Ishan Naik — Wed, 07 Oct 2026 03:25:01 +0000

A person can take thirty photos of the same face and still produce a timelapse that looks like camera shake. On Monday they stand closer to the mirror. On Tuesday they tilt their phone. By Friday they frame their eyes near the top of the image.

For fitness, skincare, and haircut timelines, viewers need to see the change in the person without chasing their face around the screen. In Phases, the useful visual reference is the eye line: keep both eyes at the same output coordinates across the sequence.

This article develops the React Native and Expo architecture for that workflow: detect landmarks on the device, compute a two-point transform, retain originals in local storage, and render a reel without a rendering server.

Implementation scope: the public Phases site currently describes a browser app that users can add to their home screen. It also describes consent-based analytics. The native Expo architecture and zero-telemetry policy below describe the reference design for this article, rather than a verified description of that deployed browser build. The project link is github.com/Ishannaik/phases; the implementation examples below stand on their own.

Separate the photograph from its alignment

A capture guide helps the user repeat their pose, but it cannot guarantee matching camera distance or roll. I would keep the original photo and store its alignment metadata beside it. That lets the user change the reel's framing without reshooting or accumulating JPEG compression from repeated edits.

flowchart TD
    A[Camera capture] --> B[Normalize orientation and mirroring]
    B --> C[On-device facial landmark detection]
    C --> D{Usable eye anchors?}
    D -->|Yes| E[Compute affine matrix]
    D -->|No| F[Ask user to retake or mark anchors]
    B --> G[Original photo in app filesystem]
    E --> H[SQLite metadata and transform]
    G --> I[Local Canvas or WebGL composite]
    H --> I
    I --> J[On-device video encoder]
    J --> K[Timelapse reel on device]
    G -. Optional user-enabled backup .-> L[Cloud backup]

The engineer should treat capture, detection, and rendering as separate steps. After a successful detection, the renderer needs the photo URI and six transform coefficients. It does not need another inference pass each time the user plays the timeline.

For a native app identified as io.phases.app, use its app-private filesystem for photos and SQLite for timestamps, dimensions, eye coordinates, and alignment settings. io.phases.app is an application identifier, not a portable filesystem path. Android and iOS choose the sandbox's physical location.

With Expo, expo-file-system provides document storage, and expo-sqlite provides a persistent database. Store large image files in the filesystem rather than putting base64 photo strings into database rows.

Choose eye anchors your detector can supply

With MediaPipe, you can derive eye anchors from a face mesh. The older Face Mesh API offers iris refinement through refine_landmarks; the current Face Landmarker task provides a denser landmark result. Google documents 478 landmarks for its current model bundle.

Google's canonical face model UV visualization. This repository asset illustrates landmark topology, not a Phases screenshot or a detector result from this article.

ML Kit can provide eye landmarks through its face detection API, but an eye landmark is not equivalent to a measured pupil center. If you choose ML Kit, name those anchors eye centers. If you need iris-center estimates, choose a detector configuration that supplies iris landmarks and document your index mapping against that model version.

Even an iris center gives an estimate of the visible iris, not a clinical measurement of pupil position. For framing a selfie sequence, the distinction matters because eye movement can introduce jitter. A user looking left and then right can change the anchors without moving their head. A consistent gaze and capture guide help. Eye-contour centers offer another anchor convention when gaze changes dominate the result.

I would run detection on each captured still image, with one intended face. A low-resolution preview can guide capture, but I would calculate the saved transform from the final image. Preview crops and final camera output often use different coordinate systems.

Before measuring the eye vector:

Decode the photograph into a consistent upright orientation.
Apply the chosen mirror policy to both pixels and landmarks.
Convert detector coordinates into source-image pixels.
Preserve consistent eye identities across photographs.

For a detector that returns normalized coordinates, multiply x by image width and y by image height. Measuring an angle in normalized coordinates distorts it whenever width and height differ.

Two anchors determine rotation, scale, and translation

Let the source eye anchors be:

$$
p_1=(u_1,v_1),\qquad p_2=(u_2,v_2).
$$

Choose fixed normalized output anchors:

$$
q_1=(x_1,y_1),\qquad q_2=(x_2,y_2).
$$

For horizontal eyes, choose $y_1=y_2$. In an output with width $W$ and height $H$, convert those targets to pixels:

$$
Q_1=(Wx_1,Hy_1),\qquad Q_2=(Wx_2,Hy_2).
$$

For example, on a 1080 by 1920 portrait canvas, (0.38, 0.35) and (0.62, 0.35) place the eyes at (410.4, 672) and (669.6, 672). Their separation is 259.2 pixels. These are illustrative framing choices, not measured Phases defaults.

SOURCE PHOTO                         OUTPUT CANVAS

                 p2 *                Q1 *=============* Q2
                   /                     fixed eye axis
                  / d
             p1 *

       tilted eye axis               horizontal eye axis
       variable separation           fixed separation

             translate + rotate + uniform scale

Define the source and target eye vectors:

$$
d=p_2-p_1,\qquad D=Q_2-Q_1.
$$

Then calculate:

$$
s=\frac{\lVert D\rVert}{\lVert d\rVert},\qquad
\theta=\operatorname{atan2}(D_y,D_x)-\operatorname{atan2}(d_y,d_x).
$$

Use the source midpoint $m=(p_1+p_2)/2$ and target midpoint $M=(Q_1+Q_2)/2$. For any source pixel $p$:

$$
T(p)=sR(\theta)(p-m)+M,
$$

where:

$$
R(\theta)=
\begin{bmatrix}
\cos\theta & -\sin\theta\
\sin\theta & \cos\theta
\end{bmatrix}.
$$

You can write this as a homogeneous affine matrix:

$$
\begin{bmatrix}
x'\y'\1

\end{bmatrix}

\begin{bmatrix}
a&c&e\b&d&f\0&0&1
\end{bmatrix}
\begin{bmatrix}
x\y\1
\end{bmatrix}.
$$

Two point pairs determine this similarity transform, which uses uniform scale, rotation, and translation. They do not determine an arbitrary six-parameter affine transform with shear and independent axis scales. A similarity transform belongs to the affine family and preserves the face's proportions.

For a horizontal target eye line, $\theta$ cancels the source eye angle. The coordinate system uses positive y downward, as Canvas does; calculate both angles in that same system.

Calculate the Canvas coefficients in TypeScript

The following reference implementation accepts source anchors in pixels and target anchors in normalized output coordinates. It returns the six values in the order that Canvas expects for setTransform(a, b, c, d, e, f).

type Point = Readonly<{ x: number; y: number }>;
type Affine = [number, number, number, number, number, number];

function eyeAlignment(
  source1: Point,
  source2: Point,
  target1: Point,
  target2: Point,
  width: number,
  height: number,
): Affine {
  const values = [
    source1.x, source1.y, source2.x, source2.y,
    target1.x, target1.y, target2.x, target2.y,
    width, height,
  ];
  if (!values.every(Number.isFinite) || width <= 0 || height <= 0) {
    throw new Error("Alignment needs finite coordinates and positive dimensions");
  }
  if ([target1.x, target1.y, target2.x, target2.y]
      .some(value => value < 0 || value > 1)) {
    throw new Error("Target anchors must lie within normalized output bounds");
  }

  const sx = source2.x - source1.x;
  const sy = source2.y - source1.y;
  const tx = (target2.x - target1.x) * width;
  const ty = (target2.y - target1.y) * height;
  const sourceDistance = Math.hypot(sx, sy);
  const targetDistance = Math.hypot(tx, ty);
  if (sourceDistance < 1 || targetDistance < 1) {
    throw new Error("Eye anchors must be distinct");
  }

  const scale = targetDistance / sourceDistance;
  const angle = Math.atan2(ty, tx) - Math.atan2(sy, sx);
  const a = scale * Math.cos(angle);
  const b = scale * Math.sin(angle);
  const c = -b;
  const d = a;
  const mx = (source1.x + source2.x) / 2;
  const my = (source1.y + source2.y) / 2;
  const qx = (target1.x + target2.x) * width / 2;
  const qy = (target1.y + target2.y) * height / 2;
  const e = qx - a * mx - c * my;
  const f = qy - b * mx - d * my;
  return [a, b, c, d, e, f];
}

function drawAlignedFrame(
  ctx: CanvasRenderingContext2D,
  image: CanvasImageSource,
  imageWidth: number,
  imageHeight: number,
  matrix: Affine,
): void {
  ctx.save();
  try {
    ctx.setTransform(1, 0, 0, 1, 0, 0);
    ctx.clearRect(0, 0, ctx.canvas.width, ctx.canvas.height);
    ctx.fillStyle = "#000";
    ctx.fillRect(0, 0, ctx.canvas.width, ctx.canvas.height);
    ctx.setTransform(...matrix);
    ctx.drawImage(image, 0, 0, imageWidth, imageHeight);
  } finally {
    ctx.restore();
  }
}

Use imageWidth and imageHeight from the same oriented image coordinate system as the source anchors. The code assumes the caller owns the canvas, with no inherited clipping region.

The one-pixel check prevents division by a degenerate eye vector. Production acceptance needs a stronger, image-relative criterion: a two-pixel eye separation on a large image can still produce an unusable scale. Check confidence, face size, and acceptable scale before saving alignment metadata.

To check the matrix mathematically, apply it to each source anchor. You should recover the corresponding target pixel coordinate:

a*u1 + c*v1 + e = W*x1
b*u1 + d*v1 + f = H*y1

a*u2 + c*v2 + e = W*x2
b*u2 + d*v2 + f = H*y2

These equations provide useful unit-test assertions with a floating-point tolerance. They describe invariants, not test results from a running Phases build.

React Native needs a rendering boundary

React Native does not expose a browser DOM Canvas as a built-in drawing surface. The CanvasRenderingContext2D example belongs in a browser or a WebView. In a native renderer, adapt the same coefficients to that renderer's matrix convention.

You can use a WebView-hosted Canvas for a shared web rendering path, or use a native GPU drawing surface. With WebGL, upload a photo texture and apply the transform while drawing a quad. Account for the renderer's origin, texture orientation, and matrix layout; copying Canvas coefficients into an unrelated matrix API can invert or transpose the result.

For MediaPipe or ML Kit integrations that require native code outside Expo Go, create an Expo development build. Installing a JavaScript wrapper cannot add its native implementation to the Expo Go binary. Expo documents this boundary in its development build guidance.

Keep decoded image data near the detector and renderer. Passing a full-resolution base64 image through repeated JavaScript bridge messages adds allocation and copying. Transfer a URI or native image handle where the integration supports it.

Render frames locally, then encode locally

Drawing aligned photos on a canvas gives you frames. To export a video file, you also need an encoder and a container writer.

In a native implementation, connect the rendering surface to an on-device encoder. In a browser implementation, select a supported local recording or encoding API and handle device-specific codec availability. Do not assume a Canvas screenshot sequence equals an MP4 export.

For an export with one photograph per time interval, calculate presentation timestamps from the intended playback cadence. Processing speed should not determine the video's timing. A slow decode must delay export work, not stretch one day into a longer frame.

Memory makes sequential processing important. One 1080 by 1920 RGBA frame takes 8,294,400 bytes, about 7.9 MiB before renderer and decoder overhead. Holding 365 such frames would consume about 2.8 GiB in pixel buffers alone. Decode a bounded number of photos, render a frame, submit it to the encoder, and release resources as the encoder permits.

You should also choose how to handle uncovered canvas areas. Rotation can expose triangles at the corners; scaling cannot recover pixels outside the original capture. Use a consistent background, crop, or capture margin. Avoid changing the crop per frame, since that reintroduces apparent zoom.

Local storage and an optional backup path

A useful local record links a photo URI to its capture time, oriented dimensions, source eye anchors, detector version, and alignment settings version. Retain the originals so you can recalculate transforms after changing the target eye positions.

Coordinate filesystem writes with database commits. Write the image into durable document storage before committing a row that references it. If the database commit fails, remove the new file or reconcile it on the next launch. SQLite cannot roll back a separate filesystem write.

The reference design uses a zero-telemetry policy: no analytics events, session replay, or automatic diagnostic uploads. Developers must apply that policy to crash-reporting SDKs and dependencies as well as application code. Local inference does not by itself guarantee zero network traffic.

For offline detection on first use, package the model with the app. A model download on first launch introduces a network prerequisite even if subsequent inference stays local.

Keep cloud backup outside the alignment and rendering path. A user who declines backup should still capture, align, preview, and export. If they enable backup, explain which originals and metadata you upload, request the provider's permissions, and make local deletion versus remote deletion explicit. App-private storage also does not imply encryption or exclusion from operating-system backups; configure those policies for the threat model you support.

The public Phases FAQ describes optional Google Drive backup and analytics that remain off until consent. Readers evaluating the deployed app should use that published policy rather than the stricter native reference policy above.

Eye alignment has a defined limit

A two-eye transform corrects translation, camera roll, and apparent face scale. It cannot correct a person turning their head, pitching their chin, changing expression, or photographing themselves under a different light source. On a fitness timeline, the eyes also cannot guarantee matching shoulder position or body pose.

I would keep those constraints visible in capture UX: guide the user toward the same gaze, pose, and lighting, then use alignment to absorb small framing errors. For a failed detection or an occluded eye, offer a retake or manual anchors. Do not invent a plausible transform and label it a successful alignment.

Phases' core visual goal is concrete: put the eye axis in the same place across days. With consistent image coordinates, a four-degree-of-freedom transform, and a local rendering pipeline, you can achieve that framing without sending a user's progress photos to an inference or rendering service.

References

Written by Ishan Naik.

Bypassing TLS Fingerprints Without Proxies: Building a Bun & SQLite Ticket Watcher for BookMyShow

Ishan Naik — Wed, 07 Oct 2026 03:24:29 +0000

I sent BookMyShow requests from an Oracle Cloud VPS and got 403. I changed the User-Agent, added Chrome headers, kept cookies, and forced HTTP/1.1. BookMyShow rejected those requests too.

On the same VPS, node-tls-client with the safari_ios_18_0 profile returned 200. I kept the datacenter IP and dropped the proxy shopping.

That experiment shaped SeatSniper, my self-hosted ticket watcher. Users submit a BookMyShow link through a Discord slash command. I store their watches in SQLite, share upstream requests across users, and send notifications when matching dates or cinemas appear. I run the bot with Bun 1.2, TypeScript, and Discord.js v14.

SeatSniper observes listings. I do not automate purchases, hold seats, or fill carts. A notification means I found a matching listing during a poll, not that I reserved a ticket.

Diagnose the handshake before renting an IP

A browser sends more than HTTP headers. During TLS negotiation, the client proposes cipher suites, extensions, supported groups, and application protocols through its ClientHello. Browser families produce recognizable combinations. A server can also inspect HTTP/2 settings after the handshake.

Security teams use JA3 and JA4 to summarize aspects of those fingerprints. Neither fingerprint represents a complete browser identity, and neither tells an operator the entire reason for a Cloudflare decision. IP reputation, geography, request volume, and challenges can still affect access.

For this deployment, I could isolate the client fingerprint as a practical blocker: I changed the client while keeping the VPS fixed. An apparent datacenter-IP ban can hide a TLS or HTTP/2 fingerprint problem. Buying a residential proxy would have changed another variable before I understood the first one.

I recorded these results on July 27, 2026 in the repository's access findings:

Environment	Client	Result
Oracle VPS, datacenter IP	Bare curl	`403`
Same VPS	Curl with Chrome User-Agent and headers	`403`
Same VPS	Bun `fetch()`	`403`
Same VPS	`node-tls-client`, `safari_ios_18_0`	`200`
Same VPS	Python `curl_cffi`, Safari or Edge impersonation	`200`
Residential connection	Curl on Raspberry Pi, OpenSSL 1.1.1w	`403`

The Python result matters: the language did not determine access. Python curl impersonation worked; a conventional client could fail on a residential connection.

In a ten-request Safari-profile run on Oracle, I recorded ten 200 responses, with 37 ms minimum, 48 ms median, and 116 ms maximum latency. Those numbers describe that experiment, not a latency guarantee or a benchmark against every proxy provider.

Keep the browser profile coherent

I use node-tls-client, which wraps the Go tls-client implementation. Through that stack, I select a browser-shaped TLS ClientHello and HTTP/2 configuration without launching a browser process.

In src/bms.ts, I initialize the native layer once, then create a reusable session. I default to safari_ios_18_0 and expose BMS_TLS_PROFILE for supported Safari or Firefox profile overrides.

I send no custom headers on BookMyShow requests. In my measurements, adding a full Chrome header set to a working residential Bun request changed the response from 200 to 403. A Chrome User-Agent does not change the TLS handshake. I treat the mismatch as a reason to keep the profile and request shape together, rather than stacking headers from unrelated examples.

I cannot promise that Safari impersonation will keep working. Cloudflare can change its scoring, BookMyShow can add a JavaScript challenge, and operators outside India can encounter geographic restrictions. SeatSniper reports blocked requests instead of treating them as an absence of tickets. Respect the site's terms and restrictions; this setup provides no authorization to evade access controls or increase traffic.

Store user intent once, share upstream work per cycle

Fifty users can watch the same film. If I fetch the same listing fifty times, I increase load without learning anything new.

I separate two kinds of deduplication:

Persistent watch deduplication: SQLite rejects a duplicate watch through UNIQUE (user_id, event_code, date).
Request coalescing: an in-memory map shares one promise for a (city, eventCode) lookup during a poll cycle.

SQLite stores the watch queue and notification history. I do not store the network cache in SQLite. The per-cycle promise maps live in src/bms.ts, and I reset them through beginCycle().

sequenceDiagram
    actor User
    participant Bot as Discord bot
    participant DB as SQLite watch queue
    participant Cache as Per-cycle promise map
    participant BMS as BookMyShow via Safari TLS
    participant Discord as Discord delivery

    User->>Bot: /watch link date filters
    Bot->>BMS: Validate movie through Safari profile
    BMS-->>Bot: Movie title and listing data
    Bot->>DB: Insert watch with unique user/event/date
    DB-->>Bot: Saved ID or duplicate
    Bot-->>User: Watch confirmation

    loop Each poll cycle
        Bot->>DB: Read active watches
        Bot->>Cache: Clear previous cycle
        Bot->>Cache: Lookup city and event
        alt First watch for this movie
            Cache->>BMS: Fetch bookable dates
            BMS-->>Cache: Dates, venues, format chips
        else Another watch for same movie
            Cache-->>Bot: Reuse stored promise
        end
        Cache-->>Bot: Shared availability result
        Bot->>Bot: Apply watch-specific filters
        opt Matching new availability
            Bot->>Discord: Send direct message
            Discord-->>User: Ticket notification
            Discord-->>Bot: Delivery outcome
            Bot->>DB: Record seen state or retire dated watch
        end
    end

I include the city in the cache key because BookMyShow returns different cinemas and showtimes for Mumbai, Delhi, and Pune. I omit the slug because I measured that BookMyShow uses the event code as the authoritative movie identifier.

For fifty watches on the same movie and city, I make one shared bookable-date request per cycle. That does not mean the entire cycle must cost one request. Once a date opens, I may need showtimes for it. I cache those requests under (city, eventCode, date). Format-specific child events can add requests too.

A coalesced loop with rate jitter

This reduced excerpt shows the repository's polling structure. checkWatch() uses bookableDatesCached() and, when needed, fetchShowtimesCached(). I omit command handling and notification formatting so the cache boundary remains visible.

import {
  beginCycle,
  coalescedCount,
} from "./bms.ts";
import { allWatches } from "./db.ts";
import { staggerBounds, staggerDelayMs } from "./stagger.ts";

const bounds = staggerBounds(); // Defaults: 2000 to 5000 ms

async function poll() {
  const watches = allWatches();
  beginCycle();

  for (const watch of watches) {
    try {
      // Existing application functions from src/index.ts:
      if (!(await expireStale(watch))) {
        await checkWatch(watch);
      }
    } catch (error) {
      console.error(`[watch ${watch.id}] poll failed:`, error);
    }

    await Bun.sleep(staggerDelayMs(bounds));
  }

  console.log(
    `[poll] ${watches.length} watches; ` +
    `${coalescedCount()} requests saved`,
  );
}

Under the cache, I insert the promise before returning it:

const key = `${target.city}|${target.eventCode}`;
const hit = cycle.get(key);
if (hit) return hit;

const pending = fetchBookableDates(target);
cycle.set(key, pending);
return pending;

By caching the promise, I share an in-flight request as well as a completed answer. I keep that answer within the cycle, then fetch fresh data next time. A rejected promise also remains shared within that cycle, so I avoid fifty retries against the same blocked endpoint.

I configure the delay through STAGGER_MS_MIN and STAGGER_MS_MAX. The defaults sample a uniform delay from 2,000 ms up to 5,000 ms between watches. Jitter spreads activity; it does not grant permission to poll faster or solve a challenge.

I also pay for that pacing in notification latency. Fifty watches incur about 175 seconds of stagger delay on average, before network and delivery time. The repository schedules polls every 600 seconds by default. Users should read that as periodic detection, not an instantaneous guarantee. At larger watch counts, an operator must account for cycle duration and the current interval scheduler's potential for overlapping cycles.

Read the date on each show

An HTTP 200 and a page full of showtimes can still produce the wrong answer.

BookMyShow can return the nearest bookable date when I request a date that has not opened. The URL and page-level current-date field can echo my requested date while the show objects describe a different day.

I check the showDateCode inside each show's additionalData:

const matching = shows.filter(
  (show) => show.showDateCode === requestedDate,
);

In the recorded test, I requested July 30 and parsed 34 shows. None carried showDateCode: "20260730"; they belonged to July 27. Counting shows would have produced a false notification.

For the shared movie-level check, I fetch the buytickets HTML using the probe date 20991231. BookMyShow includes the requested date in its date list, so I remove that sentinel from the parsed dateCode values. I verified the remaining date sets against individual date requests for three films in the recorded investigation. After a positive date-level result, I inspect actual showtimes before sending a dated-watch alert.

I validate the page before accepting an empty result. The current provider checks for window.__INITIAL_STATE__ and a movie title. A challenge page without the app marker raises an error. A recognizable movie page with no showtimesSections can represent a legitimate empty listing. That distinction matters when upstream HTML changes: I need an error for an unknown page, not a fabricated “tickets have not opened” answer.

Keep the filter engine tied to show data

A watcher becomes noisy if a user wants IMAX and I notify them about any screening.

Users can submit filters through /watch:

/watch link:<BookMyShow URL> date:any
       format:IMAX,4DX theatre:PVR,INOX
       days:fri,sat after:18:00 before:23:00

I normalize format names and compare them without case or whitespace sensitivity. IMAX matches IMAX 3D; SCREENX matches SCREEN X. BookMyShow also lists some formats under separate child event codes. I parse the format-selector chips and inspect matching child events, rather than assuming the parent event contains every screen type.

For theatres, I match a case-insensitive substring of the venue name or venue code. A user can choose PVR or paste a code such as IMOB. I apply theatre restrictions to new-cinema alerts using the venue data I already fetched.

Time windows use Indian Standard Time, UTC+05:30, regardless of the host's timezone. I convert BookMyShow's IST show datetime into an epoch and compare the show's IST wall-clock minutes against the user's bounds. I treat after:18:00 as inclusive and before:23:00 as exclusive. I reject a window that wraps through midnight; users cannot express after:23:00 before:01:00 as one watch window.

Subscriptions need an extra distinction. A date:any watch can report a new date or a new cinema. I apply format, weekday, and showtime checks to date alerts. I do not claim that a new-cinema alert satisfies those checks: I detect fresh cinemas by venue code, and apply the theatre filter there. The command documentation spells out that boundary.

Persist notification history, then handle delivery failure

I use Bun's built-in bun:sqlite API in src/db.ts. I keep watches, seen_dates, and seen_venues in seatsniper.db, or the path configured through DB_PATH.

seatsniper.db
+ watches
|   user, city, event, date, filters, failure state
+ seen_dates
|   watch_id + date_code
+ seen_venues
    watch_id + venue_code

Per-cycle memory
+ city | event         -> Promise<bookable dates>
+ city | event | date  -> Promise<showtimes>

I enable WAL mode and foreign keys. WAL mode can create seatsniper.db-wal and seatsniper.db-shm, so “single-file database” describes deployment simplicity, not a promise that a running SQLite process uses only one filesystem entry. For live backups, use SQLite-aware backup tooling rather than copying the main file while ignoring pending WAL writes.

I seed a subscription's seen-state from the listings available when the user creates it. I then notify them about later additions. For a dated watch, I send one alert and retire the watch after successful delivery.

I attempt the DM first. If Discord rejects it, I try the originating text channel and tell the user that I used the fallback. If both attempts fail, I retain the dated watch or leave subscription additions unrecorded, then retry on a later poll.

I record seen-state after delivery. That ordering reduces lost notifications, but I cannot make SQLite writes and Discord delivery one atomic transaction. A crash after Discord accepts a message and before I commit seen-state can cause a duplicate on restart. Operators should expect that failure window rather than promise exactly-once messaging.

For upstream checks, I track consecutive failures and send a warning at the third failure. I reset the counter after a successful check. That lets a user distinguish an unavailable movie date from a watcher that cannot read BookMyShow.

Run it without adding infrastructure

I keep the manual path small:

git clone https://github.com/Ishannaik/seatsniper.git
cd seatsniper
bun install
cp .env.example .env

Add your Discord bot token as DISCORD_TOKEN and application ID as DISCORD_CLIENT_ID in .env. Keep those values out of Git. Then register commands and start the bot:

bun run commands
bun run start

The repository also provides Docker instructions and a Linux/macOS installer. I would inspect the installer before running a downloaded shell script. Windows users can use manual setup or Docker.

For monitoring, I can configure UPTIME_KUMA_PUSH_URL. I send its heartbeat after a completed poll, including idle cycles. A running container alone does not prove that the bot logged into Discord or completed an upstream check.

I chose this design for a small self-hosted service: one Bun process, one local SQLite database, one native TLS client, and Discord delivery. I still have to preserve the database volume, monitor failed polls, and react when BookMyShow changes its HTML or access policy.

The two decisions I would repeat are the controlled client experiment and the per-cycle cache. By keeping the VPS fixed, I found a working transport without paying for residential egress. By sharing each movie lookup, I let fifty users observe the same release without sending fifty copies of the same request.

Source and deployment instructions: Ishannaik/seatsniper. The measured access findings include the response matrix, date-substitution tests, and limits behind the claims above.

Building a Hyperlocal Rain Nowcaster on a $0 Stack: Benchmarking Open-Meteo Against Airport Radar

Ishan Naik — Wed, 07 Oct 2026 03:23:54 +0000

A rain forecast for Mumbai can tell you to carry an umbrella while your street stays dry. During the monsoon, a useful next-two-hour prediction needs more local evidence than a global model alone can provide.

I built Mumbai Rain, also called पाऊस, around that problem. I collect forecasts, compare them with observations at Mumbai airport, and train a small correction that visitors run in their browsers.

First, a qualification about the title: I do not ingest airport radar. I use METAR surface-weather reports from station VABB, Chhatrapati Shivaji Maharaj International Airport. Airport observers and instruments report present weather; I convert their precipitation codes into hourly rain labels. Radar measures precipitation across an area. A METAR report describes conditions at a station. That distinction sets the limits of the entire experiment.

The source repository contains the data diary, training code, browser arithmetic, and exported model. You can inspect the method and scoreboard without accepting a headline accuracy claim.

Start with a narrower prediction target

Engineers who build global models such as ECMWF and GFS solve atmospheric dynamics over grids. A forecast grid cell cannot resolve each Mumbai street, coastal exposure, or passing monsoon shower. Asking for a coordinate does not create street-level observational coverage.

For this project, I ask a narrower question: given the forecast inputs available now, how likely is an hourly rain observation at the airport?

I use Open-Meteo as the delivery API for two forecast streams:

best_match, the primary forecast feed, including precipitation and relative humidity.
ecmwf_ifs025, an explicit ECMWF-IFS precipitation benchmark.

I do not train a replacement for ECMWF. I train logistic regression to correct the relationship between forecast features and an independent binary observation. Visitors receive a local-coordinate forecast with a correction learned at VABB. They should not read that as a measured rain probability for every neighbourhood.

Collect forecasts before the outcome arrives

The hourly collection workflow schedules a GitHub Actions run at minute five:

schedule:
  - cron: "5 * * * *"

GitHub can delay scheduled jobs. I treat the cron as a collection schedule, not a real-time delivery guarantee.

In pipeline/log_snapshot.py, I collect at (19.12, 72.85), record the forecast issue time, and append forecast-hour rows to data/log.csv. On subsequent runs, I fetch the last 24 hours of METAR reports and fill labels for matching hours.

flowchart TD
    Clock[Hourly GitHub Actions collection] --> Forecast[Open-Meteo best_match and ECMWF-IFS]
    Forecast --> Diary[data/log.csv: forecasts with blank labels]
    Airport[VABB METAR present-weather reports] --> Labels[Convert UTC to IST; label RA and DZ]
    Labels --> Diary
    Diary --> Filter[Keep labelled forward forecasts]
    Daily[Daily GitHub Actions retraining] --> Filter
    Filter --> Train[Fit logistic regression]
    Train --> Gate[Holdout scores and purged walk-forward folds]
    Gate --> Decision{Promotion criteria met?}
    Decision -->|Yes| Export[public/model.json]
    Decision -->|No| Retain[Retain champion or evaluate raw fallback]
    Export --> CDN[Astro assets on CDN]
    CDN --> Browser[Browser loads model]
    Live[Live Open-Meteo forecast] --> Browser
    Browser --> Math[Six features and sigmoid]
    Math --> Verdict[Hourly rain calls and next-two-hour verdict]

I record both timestamps because they answer different questions:

issued_at          Forecast snapshot time, UTC
valid_at           Forecast target hour, Asia/Kolkata
fc_bestmatch_mm    Primary forecast precipitation
fc_ecmwf_mm        ECMWF forecast precipitation
fc_rh_bestmatch    Forecast relative humidity
hour               Target local hour
recent_rain_mm     Recent precipitation feature
observed_raining   Blank until labelled, then 0 or 1

I can then ask what I knew when I issued a forecast, rather than download a later forecast and pretend I had predicted the outcome.

The collector stores the returned day's hourly series, including hours that may precede the issue time. Before training, I filter those rows out. In matured(), I convert issued_at from UTC to IST and require valid_at >= issued_at. I train on forward forecasts because the browser serves forward hours.

Label rain without grading a forecast against itself

In pipeline/labels.py, I read the METAR wxString field:

Report token	Label interpretation
`RA`, including `-RA`, `+RA`, `SHRA`, `TSRA`	Rain
`DZ`	Drizzle
`BR`, `HZ`, `FG`	Mist, haze, fog: not a rain label

I convert each report timestamp from UTC to IST and floor it to the local hour. If I find multiple reports in one hour, I label that hour as rainy if any report includes rain or drizzle.

For a missing report, I leave the label blank. I do not equate missing observations with dry weather.

This gives me an independent target, with several qualifications. Airport reports can miss a shower between observations. A binary label gives me no measured rainfall amount. An hourly label loses sub-hour timing. And a dry airport cannot establish that Bandra, Thane, or a visitor's GPS coordinate stayed dry.

I also keep the recent-rain feature separate from the label. Despite the name recent_rain_mm, I compute that feature from Open-Meteo's precipitation series over the three hours before the current hour. I do not obtain a neighbourhood rain-gauge measurement through that field.

Use Git as the database, within its limits

I keep the diary in data/log.csv. The bot commits the changed CSV and health metrics after collection. In each row, I retain the forecast and later add the observed label.

For one collection point and hourly jobs, I get a readable history and a training dataset that contributors can download without credentials. I also avoid provisioning a database just to collect this experiment.

I accept the costs of that choice. The logger reads and rewrites the CSV. Repeated commits increase repository history. Separate collection and training workflows can encounter competing pushes; their individual concurrency groups do not create a shared database transaction. Git suits the current small workload, but I would revisit storage before collecting hundreds of stations.

Make the daily model earn deployment

The retraining workflow schedules a run at 01:30 UTC. It runs the Python tests, trains the candidate, refreshes health metrics, and commits an artifact if the training decision changes it.

In pipeline/train.py, I require at least 200 labelled forward rows. I also require both rainy and dry examples in training and holdout data.

I fit six features in this order:

x = [best_match_mm, ecmwf_mm, relative_humidity,
     sin(2π hour / 24), cos(2π hour / 24), recent_rain_mm]

I encode the hour as sine and cosine so midnight and 23:00 remain neighbours in the feature space. I keep the feature order identical in Python and src/lib/nowcast.js. Swapping humidity and precipitation would produce valid JavaScript and invalid predictions.

For evaluation, I use the Brier score:

$$
\operatorname{Brier} = \frac{1}{N}\sum_{i=1}^{N}(p_i-y_i)^2
$$

A confident wrong prediction incurs a large penalty. A lower score means lower squared probability error on the evaluated observations.

I compare the candidate against the existing logistic champion, a raw rain call, and climatology: the training set's rain frequency. The main holdout contains the last 20% of rows after time sorting.

Purge by time, not row count

One target hour can appear in several forecast snapshots. If I shuffle rows, I can train on one prediction of an hour and test on another prediction of the same observed event.

I add four expanding-window walk-forward folds. I place boundaries between distinct valid_at timestamps and purge six hours before each test window. I skip folds with fewer than 25 training or test rows, or without both label classes.

Time advances to the right

Fold 1: [training] [6h purge] [test]
Fold 2: [     expanded training     ] [6h purge] [test]
Fold 3: [          expanded training          ] [6h purge] [test]
Fold 4: [               expanded training               ] [6h purge] [test]

For each fold, I calculate Brier skill against the raw call:

$$
\operatorname{BSS} = 1 - \frac{\operatorname{Brier}{candidate}}{\operatorname{Brier}{raw}}
$$

I require at least two usable folds, a positive median skill, and at least two positive fold scores. For a perfect raw reference, the implementation reports zero skill rather than divide by zero.

This excerpt expresses the promotion decision using the functions and score variables from the training module:

# Score candidate, champion, raw call, and climatology on the holdout.
# Calculate fold_skills with purged expanding-window evaluation first.
walk_forward_ok = passes_walk_forward(fold_skills)

if walk_forward_ok and passes_gate(
    cand_brier=cand_b,
    champ_brier=champ_b,
    raw_brier=raw_b,
    clim_brier=clim_b,
):
    with open(MODEL_PATH, "w") as f:
        json.dump(candidate, f, indent=2)

Two implementation details matter when interpreting the benchmark:

The automated raw gate uses best_match, not ECMWF alone. The code thresholds the first feature at 0.3 mm/h to construct its raw binary forecast. I collect ECMWF as a separate benchmark and model input, but I cannot describe raw_brier as an ECMWF-only result.
The holdout gate accepts ties. passes_gate() rejects a candidate whose Brier score exceeds a reference score. The walk-forward median must exceed zero, but the holdout comparisons mean “no worse,” rather than a strict improvement against each reference.

I should also avoid promising that future skill can only improve. I evaluate each deployment against the available historical data. Weather regimes change. The code includes a conditional raw-forecast fallback when a champion loses to the raw forecast or climatology and the walk-forward check permits that decision path.

The four purged folds reduce temporal leakage, but the separate 80/20 row split does not use the same timestamp-grouping and purge logic. Repeated target hours can straddle that split. I treat the walk-forward requirement as essential and retain this limitation when reading the holdout scores.

A scorecard you can inspect

The repository's public/model.json, stamped 2026-10-06T07:40:36Z, records:

Artifact field	Value
Training rows	6,904
Holdout rows	1,727
Candidate Brier	0.0936
Raw best-match call Brier	0.2131
Climatology Brier	0.1088
Previous champion Brier	0.0943
Walk-forward median BSS	0.6236

The four fold skill values are 0.6555, 0.8399, 0.5918, and 0.5734. These are historical artifact values, not a benchmark I reran for this article. The row counts include repeated target hours from different issue times; they do not represent 8,631 independent weather events.

Export arithmetic, serve it in the browser

I export six coefficients, an intercept, feature names, and evaluation metadata to public/model.json. The payload fits within roughly 2 KB; the current artifact is smaller. Visitors fetch the model as a static asset, then fetch a live Open-Meteo forecast at their selected coordinates.

For each hour, I calculate:

$$
z = b + \sum_{j=1}^{6} w_j x_j,
\qquad p = \frac{1}{1+e^{-z}}
$$

Here is an illustrative input using the coefficients in the dated artifact, not a recorded weather observation:

best_match precipitation    1.0 mm
ECMWF precipitation         0.6 mm
relative humidity          90.0 percent
local hour                 18:00
hour sine                  -1.0
hour cosine                 0.0
recent precipitation        2.0 mm

The arithmetic is:

z = -16.791748
    + 0.300222 × 1.0
    + 0.667161 × 0.6
    + 0.173399 × 90.0
    + (-0.271461) × (-1.0)
    + (-0.900516) × 0.0
    + 0.041041 × 2.0

z ≈ -0.131776
p = 1 / (1 + exp(0.131776)) ≈ 0.4671

The browser calls an hour rainy at p >= 0.5, so this example falls below the rain-call threshold even though both raw precipitation inputs exceed 0.3 mm/h.

The JavaScript implementation clamps the logit to the same range as Python:

const z = model.intercept + model.weights.reduce(
  (sum, weight, i) => sum + weight * features[i],
  0
);
const clamped = Math.max(-60, Math.min(60, z));
const probability = 1 / (1 + Math.exp(-clamped));

I evaluate each forecast hour in the requested window and build the verdict from those hourly calls. When I display precipitation intensity, I use the raw forecast amount. Logistic regression returns a probability, not millimetres of rain. The maximum hourly probability also should not be interpreted as the probability of any rain across the entire window.

Account for the $0 claim

I use an Astro site, static model assets, keyless forecast requests, and GitHub Actions jobs on a public repository. I do not provision a backend ML inference server. For the browser path, visitors perform the six-feature calculation on their own devices.

That removes a network round trip to an inference service. It does not make the application zero-latency: visitors still download assets, fetch Open-Meteo responses, and wait on network conditions. The repository also includes an on-demand /api/nowcast endpoint for API consumers; the browser inference path does not require that endpoint.

The operating stack fits the project's current free-tier usage. I do not treat $0 as an unlimited-capacity guarantee. Forecast-provider terms, rate limits, hosting allowances, and scheduled-job availability still apply, and domain registration sits outside this runtime budget.

You can inspect the pipeline locally with the repository's documented commands:

uv sync
uv run python -m pipeline.health
uv run python -m pipeline.train

The training command applies the promotion decision and can overwrite public/model.json if the candidate qualifies. Use a working copy when experimenting.

For this project, I care about the chain from a forecast captured before an event to an independent observation and a deployment decision I can inspect. I keep that chain in a CSV, a Python module, and a small JSON artifact. Until I collect observations beyond VABB, I will describe Mumbai Rain as a forecast corrector trained at the airport, with neighbourhood forecasts and explicit geographic limits.

Local-First Semantic Search on Windows: Running SigLIP2 and DINOv3 with Tauri 2 and ONNX

Ishan Naik — Wed, 07 Oct 2026 03:23:22 +0000

I built PixaFind for the search you do when you remember a file's contents but have forgotten its name. You might remember a cat sitting in sunlight, a whiteboard from a meeting, or a paragraph about a budget. None of those memories give you a path to type into Explorer.

On Windows, I use a Tauri 2 shell, a Rust backend, ONNX Runtime inference, and local SQLite vector storage. SigLIP2 handles text-to-image search. DINOv3 handles image-to-image similarity. For documents, I combine dense embeddings with a BM25 keyword index.

The engineering cost sits in the indexing pipeline: decoding files, preparing model inputs, running inference, and keeping the index consistent as users edit their folders.

Put the inference boundary on the user's machine

I keep file access, inference, and retrieval in the Rust backend. Users interact with a floating search window through a global hotkey, Ctrl+Space, without switching away from their current application.

The native Tauri shell weighs about 5 MB. That figure describes the executable, not the full installation. Users also need model weights, ONNX Runtime dependencies, and index storage. The release README describes a one-time model download of roughly 500 MB.

Tauri uses the system webview on Windows. I avoid shipping a separate Chromium distribution, but I still have to account for webview memory, model memory, and GPU allocations. A small executable does not imply a 5 MB runtime footprint.

This diagram shows the architecture at the component level, rather than private source-code interfaces:

flowchart LR
    F["Selected folders"] --> W["Filesystem watcher"]
    W --> C["Rust: mtime and SHA-256 change detection"]
    C --> P["Decode images or extract document text"]
    P --> O["ONNX Runtime: DirectML, CUDA, or CPU"]
    O --> V["Vector DB: local SQLite storage"]
    P --> B["BM25 keyword index"]
    V --> R["Rust retrieval and ranking"]
    B --> R
    H["Global hotkey"] --> U["Spotlight UI: Tauri 2"]
    U --> Q["Query or selected image"]
    Q --> O
    R --> U

I separate background indexing from interactive retrieval because the two workloads compete for resources. During indexing, a user may still want to search the files that have finished processing. An implementation needs bounded work queues and an explicit policy for sharing GPU time; launching an inference task for every filesystem event would exhaust memory before it improved throughput.

Use SigLIP2 for descriptions, DINOv3 for visual neighbors

For a query such as cat in a sunbeam, I need an image representation that shares a space with a text representation. SigLIP2 supplies that alignment. During indexing, I encode an image. At search time, I encode the user's description and compare it with the stored image embeddings.

The user does not need to tag the image or include the word cat in its filename. Zero-shot matching means I can search with a description without training a classifier for each phrase.

For normalized embeddings, cosine similarity reduces to a dot product:

query text -> SigLIP2 text encoder  -> q
photo      -> SigLIP2 image encoder -> v

score(q, v) = sum(q[i] * v[i])

A description such as blurry photo of whiteboard asks for visual meaning. It does not guarantee that I can retrieve a sentence written on that whiteboard. Users still depend on the image resolution and the model's ability to recognize the scene. Exact text inside an image requires an OCR path; semantic image matching alone does not establish one.

When a user selects a photo and asks for similar images, I use DINOv3. With that route, I compare visual embeddings from the selected image against visual embeddings from the library. The user can look for similar compositions or objects without translating them into a sentence.

I keep the two embedding spaces separate. A DINOv3 vector and a SigLIP2 text vector do not acquire compatible meaning because both contain floating-point numbers. Each search route needs the matching model, preprocessing, and vector collection.

flowchart TD
    T["Text: cat in a sunbeam"] --> ST["SigLIP2 text encoder"]
    I["Indexed image"] --> SI["SigLIP2 image encoder"]
    ST --> S["Compare within SigLIP2 space"]
    SI --> S
    X["Selected image"] --> DX["DINOv3 encoder"]
    I --> DI["DINOv3 encoder"]
    DX --> D["Compare within DINOv3 space"]
    DI --> D
    S --> A["Rank image results"]
    D --> A

Run ONNX inference without guessing the model contract

I use ONNX Runtime to execute the exported models on Windows. PixaFind supports DirectML and CUDA acceleration, with a CPU fallback. DirectML covers compatible DirectX 12 GPUs across vendors; CUDA targets supported NVIDIA hardware.

I still need to ship a runtime that contains the selected execution provider. Enabling a Rust Cargo feature does not install CUDA libraries or give an ONNX Runtime binary DirectML support. I also need to check the exported graph's operators, tensor shapes, and provider compatibility.

The following example uses the documented API from ort 2.0.0-rc.10. It illustrates a DirectML image-embedding inference boundary, not a copy of PixaFind's private implementation. The caller supplies the actual model path, tensor names, spatial dimensions, and preprocessed pixels from its export contract.

use std::path::Path;

use ort::{
    execution_providers::DirectMLExecutionProvider,
    session::Session,
    value::TensorRef,
};

fn open_image_encoder(model_path: &Path) -> ort::Result<Session> {
    Session::builder()?
        .with_parallel_execution(false)?
        .with_memory_pattern(false)?
        .with_execution_providers([
            DirectMLExecutionProvider::default().build(),
        ])?
        .commit_from_file(model_path)
}

fn infer_embedding(
    session: &mut Session,
    input_name: &str,
    output_name: &str,
    height: usize,
    width: usize,
    pixels_nchw: &[f32],
    destination: &mut Vec<f32>,
) -> ort::Result<()> {
    // The tensor view borrows the caller's preprocessed image buffer.
    let input = TensorRef::from_array_view((
        [1usize, 3, height, width],
        pixels_nchw,
    ))?;

    let outputs = session.run(ort::inputs![input_name => input])?;
    let (_shape, embedding) =
        outputs[output_name].try_extract_tensor::<f32>()?;

    // Preserve the result after the runtime output values leave scope.
    destination.clear();
    destination.extend_from_slice(embedding);
    Ok(())
}

I reuse the session across images instead of loading model weights for each forward pass. I borrow the input buffer and copy the output into caller-owned storage because I need that embedding after the runtime releases its output values. The caller can reuse the destination allocation across files.

The caller must decode the image, apply the export's resize or crop rule, normalize channels with the correct constants, and produce the expected NCHW layout. It must also verify that the chosen output contains a pooled image embedding rather than logits or a sequence of patch features. Changing any of those choices can change retrieval quality without triggering a tensor-type error.

For SigLIP2 text inference, I need a separate input contract: the matching tokenizer, token IDs, padding policy, and any required mask tensors. I cannot substitute image preprocessing or an unrelated tokenizer.

Microsoft's DirectML execution-provider documentation requires sequential graph execution and disabled memory-pattern optimization. It also prohibits concurrent Run calls on the same DirectML session. That constraint affects worker design: I serialize access to a shared session, or provision separate sessions and accept their additional memory cost.

The documentation now describes DirectML as being in sustained engineering, with new Windows deployment development moving toward WinML. For developers choosing a runtime today, that distinction matters even when an existing DirectML deployment continues to work.

Keep exact document terms alongside dense embeddings

For document search, I combine dense vector retrieval with BM25. The release README documents approximately 30 document extensions, including .pdf, .docx, .pptx, .md, .txt, and source-code formats. The product website advertises a broader 76-plus-format count. I use the release README's narrower document scope here rather than treating those two counts as interchangeable.

A developer searching for vacation policy may want a paragraph about annual leave. Dense embeddings can retrieve that semantic relationship. Another developer searching for ERR_CONNECTION_RESET, a function name, or an invoice identifier needs exact terms. BM25 covers that lexical route.

For a hybrid implementation, I would use this retrieval sequence:

Extracted document text
    |
    +-> bounded text chunks -> dense embeddings -> semantic candidates
    |
    +-> tokenized text      -> BM25 index        -> keyword candidates
                                                    |
                              merge, deduplicate, rank by file

This sketch describes a design pattern, not a claim about PixaFind's private chunk size or fusion formula. The public release repository documents hybrid search without publishing those internals.

Developers need a ranking policy because BM25 scores and vector similarities have different scales. Adding the raw values can let one route dominate by numerical range. Rank-based fusion offers one option: assign a contribution according to a candidate's position in each list, then deduplicate document chunks before presenting file results. Tuning that policy requires queries from the target library, including both paraphrases and exact identifiers.

Text extraction also sets a ceiling on recall. A scanned PDF may contain pixels without a text layer. Office documents can include tables whose reading order affects the extracted text. Source-code tokenization can split identifiers that users expect to search as a unit. I would inspect extraction output before blaming the embedding model for a missing result.

Avoid paying for the same forward pass twice

I use modification-time checks and SHA-256 content hashing to avoid redundant inference on unchanged files. Reading metadata costs less than decoding an image and running a vision encoder. Hashing costs a full read of the file, so I do not treat it as free.

The conceptual decision tree looks like this:

Filesystem event
    |
    v
Compare stored metadata with current metadata
    |
    +-> unchanged: retain the existing index entry
    |
    v
Compute SHA-256 for a changed candidate
    |
    +-> same content digest: update metadata, retain embeddings
    |
    v
Decode or extract -> run inference -> replace index entries

Modification times provide a cheap filter, not proof of identical content. Users can restore timestamps, and some workflows preserve them while replacing files. A correctness-focused implementation needs reconciliation or content verification for those cases. It also needs to avoid committing an embedding for bytes that changed midway through the read.

For index maintenance, I would update file metadata and its associated vectors in one SQLite transaction. Deletions need removal from both vector and keyword search. A rename should preserve the relationship between the searchable content and its current path rather than leave an obsolete result that the user cannot open.

The content digest answers whether the file changed. It does not answer whether its embedding contract changed. After upgrading a model, tokenizer, or image preprocessing rule, developers need to invalidate the affected embeddings even when the source bytes remain identical. Mixing model revisions inside one vector collection produces rankings that users cannot interpret.

Budget for the index as well as the models

Local SQLite storage keeps vectors and file metadata on the user's disk. I do not need a remote vector service for this architecture, but I still need a retrieval strategy that fits the library size. Storing vectors in SQLite alone does not establish whether an implementation uses an exact scan or an approximate nearest-neighbor index.

For float32 storage, I can estimate the vector payload before accounting for database pages and metadata:

payload bytes = item count * dimensions * 4

Illustrative sizing, not PixaFind's model dimensions:
100,000 items * 768 dimensions * 4 bytes = 307,200,000 bytes
                                               about 293 MiB

If I store a second image embedding for visual similarity, I add its own dimensionality and item count to that calculation. Document chunks can create several vectors per file. GPU inference reduces compute time; it does not reduce those disk costs.

I would measure decode time, inference time, database write time, and interactive query latency as separate stages. Without hardware, model export, batch size, and library composition, a single indexing-speed number tells a developer little. This article makes no benchmark claim for those stages.

Draw the offline boundary around setup and search

PixaFind performs indexing and search on the machine, stores the index locally, and sends no telemetry. Users do not upload filenames, file contents, thumbnails, or embeddings to a search service.

Installation has a separate lifecycle. The release README describes first-launch model downloads and an in-app updater. Users therefore need network access for normal initial provisioning, even though subsequent search needs none. I would not describe that bootstrap process as zero network activity.

For an air-gapped deployment, an operator needs to provision the installer, runtime dependencies, and complete model assets before disconnecting the machine. Offline use assumes those assets already exist locally. The public README does not document a dedicated offline model-import command, so I cannot offer one here.

Local storage also requires a threat model. An embedding index can expose information about the source library to someone with access to that Windows account or disk. Keeping the computation local removes the remote search-service boundary; users still need filesystem permissions, disk encryption where appropriate, and a policy for deleting index data.

Try the search routes on your own folders

Download the Windows installer from PixaFind Releases, complete model provisioning, and choose a folder you want to index. The public repository hosts installers and update artifacts. PixaFind is commercial software, and I have not published its application source there.

To evaluate retrieval, choose queries with different demands:

Route	Example	Check
Text-to-image	`cat in a sunbeam`	Does the result match the remembered scene?
Text-to-image	`blurry photo of whiteboard`	Can you find the photo without knowing its name?
Image-to-image	Select a photo and request similar images	Do the neighbors share useful visual features?
Document semantics	`vacation policy`	Can you find a relevant passage phrased as annual leave?
Document keywords	An identifier you know exists in a file	Does hybrid ranking retain the exact match?

Then edit one indexed file and leave the others untouched. That exercise exposes a different part of the system: freshness, deletion handling, and the cost of incremental work. After provisioning, repeat your searches without network connectivity to evaluate the offline path.

I chose this architecture so users can search from descriptions while keeping their files and query processing on Windows. Its maintenance work remains concrete: compatible model exports, correct preprocessing, provider-specific session rules, and an index that tracks the files users have today.

Written by Ishan Naik. Product: PixaFind. Downloads and public documentation: pixafind-releases.

Breaking the DOM to Stop Doomscrolling: Glitch Shaders, Scroll Physics, and Chrome MV3 Network Throttling

Ishan Naik — Wed, 07 Oct 2026 03:22:50 +0000

Scroll through a feed long enough and DoomBreaker makes the page harder to read. Color drains. Glass cracks spread across the viewport. At full damage, Chrome blocks the requests that would fetch another batch of posts.

I built DoomBreaker around a behavioral premise: introduce discomfort into the interface you keep consuming. The base degradation mode leaves your existing content on screen and restores readability when you stop. You do not dismiss a guilt popup to return to an untouched feed.

A repository screenshot of the damaged interface, rather than a synthetic rendering.

A source note matters before the engineering details. The design brief describes exponential healing near 0.8% per second and WebGL displacement shaders. The current repository implements a different tuning: linear healing after 20 seconds of idle time, plus CSS clip-path glitches. I distinguish those implementations below. The title's network throttling refers to stopping matching feed requests, not imposing a bandwidth limit. Chrome's rule action here is block.

The current extension also includes a companion cat, optional daily budgets, and a Gatekeeper mode that enforces timed breaks. Those modes add blocking behavior beyond the original discomfort premise. This article follows the damage, rendering, and network pipeline.

One damage value across the feed

DoomBreaker uses a scalar damage value, $d \in [0,1]$. In meter.js, I keep the arithmetic separate from Chrome and DOM APIs. A content script supplies input; the meter updates a plain object with d, last, and lastTick.

For wheel input, the current calculation is:

$$
d_{next}=\min\left(1, d+\frac{|\Delta y|\,s}{40000}\right)
$$

Here, $s$ represents the popup sensitivity setting. At sensitivity 1, 40,000 accumulated pixels take a fresh meter to full damage. Reversing scroll direction still adds damage because I count absolute distance.

Wheel events report three units. In content.js, I treat pixel deltas as pixels, multiply line deltas by 16, and multiply page deltas by the viewport height. That 16-pixel conversion is a heuristic, not a measurement of the host page's line height.

I register passive input listeners and update state inside them. A 250 ms loop handles visual changes. Keeping DOM mutations out of wheel handlers avoids adding layout work to each burst of input.

Keyboard and touch scrolling need another route. I compare successive window.scrollY values, but ignore scroll events for 300 ms after a wheel event. A wheel gesture often produces both events; without that exclusion, I would charge the same gesture twice. The fallback also excludes deltas of 2,000 pixels or more. That choice avoids charging some large jumps, but can miss legitimate movement.

Short videos need a different unit

YouTube Shorts and Instagram Reels can advance without moving the document through a meaningful pixel distance. I count qualifying video-path changes instead. The current meter adds 0.06 * sensitivity per advancement, so 17 advancements reach full damage at sensitivity 1.

The intended product tuning describes Shorts and Reels as accumulating damage about three times faster than ordinary scrolling. The implementation does not multiply wheel damage by three. It assigns videos a separate unit cost. A time-based comparison depends on your scroll speed and how long you watch each video.

The initial route does not count as an advancement. Subsequent qualifying route changes do. That distinction avoids charging damage just because you opened a Shorts URL.

I store the meter under the shared damage.all key in chrome.storage.local. Switching from X to Reddit retains damage. Content scripts watch storage changes and adopt newer timestamped writes.

That synchronization has a limit: last-write-wins adoption does not provide an atomic sum of simultaneous inputs from several tabs. A shared key prevents a fresh budget per site, but a rigorous multi-tab accumulator would need a serialized owner for damage updates.

Thresholds turn arithmetic into discomfort

flowchart TD
    W[Wheel distance normalized to pixels] --> A[Add damage and clamp to 0 through 1]
    V[Shorts or Reels video advancement] --> A
    A --> D[Shared damage meter]
    I[Idle time] --> H[Apply healing using elapsed time]
    H --> D
    D --> P[Persist damage and synchronize tabs]
    D --> R[250 ms visual update loop]
    R --> B{Damage at least 0.30?}
    B -->|Yes| F[Blur and grayscale with vignette]
    R --> C{Damage at least 0.60?}
    C -->|Yes| G[Reveal SVG cracks and enable CSS glitch]
    R --> S{Damage at least 0.90?}
    S -->|Yes| K[Enable shake]
    D --> N{Damage at least 0.995?}
    N -->|Yes| M[Message service worker to install feed blocks]
    D --> U{Damage below 0.85?}
    U -->|Yes| O[Message service worker to remove feed blocks]

At 0.30, I enable blur and grayscale on the body. A separate radial-gradient overlay darkens the edges; the CSS starts its opacity ramp below the main blur threshold, at 0.25.

At 0.60, I reveal SVG cracks and enable the glitch animation. More cracks appear at 0.70, 0.80, 0.90, and 0.97. At 0.90, I add shake.

At 0.995, I request a network block. I leave that block active until damage falls below 0.85. Those separate entry and exit thresholds provide hysteresis. A meter hovering near full damage should not alternate between adding and removing Chrome rules.

The cracks have their own recovery behavior: I clear them below 0.50. The user sees cracks persist through part of the healing interval instead of watching the geometry toggle around 0.60.

Generate the cracks once, reveal them later

I generate three impact points with a seeded pseudorandom generator. Each impact gets four to six rays; each ray gets three to five jittered segments. I create two SVG paths per ray: a broad, dim backing stroke and a narrower bright stroke.

I generate that geometry once per page-session crack set. During progression, I reveal existing paths with stroke-dashoffset. I do not generate another crack on every frame.

This condensed excerpt shows the CSS/SVG mechanism. The caller supplies d from the meter and a path from the seeded geometry generator:

const SVG_NS = 'http://www.w3.org/2000/svg';

function addCrack(svg, pathData) {
  const path = document.createElementNS(SVG_NS, 'path');
  path.setAttribute('d', pathData);
  path.setAttribute('fill', 'none');
  path.setAttribute('stroke', 'rgba(255,255,255,.75)');
  path.setAttribute('stroke-width', '1.5');
  svg.appendChild(path);

  const length = Math.max(1, path.getTotalLength());
  path.style.strokeDasharray = String(length);
  path.style.strokeDashoffset = String(length);
  path.style.transition = 'stroke-dashoffset 0.7s ease-out';
  requestAnimationFrame(() => {
    path.style.strokeDashoffset = '0';
  });
}

function applyDamage(d) {
  const root = document.documentElement;
  root.style.setProperty('--d', String(d));
  root.classList.toggle('db-blur', d >= 0.30);
  root.classList.toggle('db-glitch', d >= 0.60);
}

#db-overlay {
  position: fixed;
  inset: 0;
  pointer-events: none;
  z-index: 2147483647;
}

html.db-blur body {
  filter: blur(calc((var(--d, 0) - 0.3) / 0.7 * 5px))
          grayscale(calc((var(--d, 0) - 0.3) / 0.7));
}

@keyframes db-glitch {
  0%, 12%, 100% { clip-path: none; transform: none; }
  7% { clip-path: inset(8% 0 61% 0); transform: translateX(-6px); }
  9% { clip-path: inset(55% 0 12% 0); transform: translateX(5px); }
}

html.db-glitch body {
  animation: db-glitch 2.5s steps(1, end) infinite;
}

@media (prefers-reduced-motion: reduce) {
  html.db-glitch body { animation: none; }
}

The full effects.css includes more glitch bursts, damage-scaled shake, and reduced-motion overrides for both animations.

I append the overlay to document.documentElement, outside the body I filter. This placement preserves crisp crack strokes above blurred content. With pointer-events: none, I leave links and buttons reachable through the overlay.

Filtering the body changes positioning behavior for some fixed descendants. A header can stop behaving like a viewport-fixed header. In this project I accept that distortion as part of the damaged interface, but I would not copy the technique into an ordinary UI without checking its positioning consequences.

A shader needs something to sample

A WebGL displacement shader could offset texture coordinates by scanline, time, and damage:

precision mediump float;
uniform sampler2D uTexture;
uniform float uDamage;
uniform float uTime;
varying vec2 vUv;

void main() {
  float band = floor(vUv.y * 90.0);
  float noise = fract(sin(band * 12.9898 + floor(uTime * 8.0))
                      * 43758.5453);
  float strength = max(0.0, uDamage - 0.6);
  float offset = (noise - 0.5) * 0.04 * strength;
  vec2 uv = clamp(vUv + vec2(offset, 0.0), 0.0, 1.0);
  gl_FragColor = texture2D(uTexture, uv);
}

This fragment shader illustrates the proposed rendering route; DoomBreaker does not ship it. A developer would also need vertex-shader plumbing, uniforms, and a texture source.

The texture source creates the hard problem. A WebGL canvas cannot sample an arbitrary live DOM tree as a texture. Capturing or reconstructing the page adds permission, fidelity, and update-cost questions, especially for cross-origin images and playing video. I use CSS clipping and transforms in the current extension to distort the host DOM without building that capture pipeline.

Healing: distinguish the model from the constants

For the proposed exponential model, you would apply:

$$
d(t+\Delta t)=d(t)e^{-k\Delta t}
$$

Taking a 0.8% relative reduction per second gives $k=-\ln(0.992)\approx0.00803$. Starting at 1, that model reaches the 0.85 unblock boundary after about 20.2 seconds of healing. It approaches zero without reaching it.

The README describes healing near 0.8% per second, but the current meter uses a linear subtraction:

CFG: {
  BUDGET_PX: 40000,
  VIDEO_HIT: 0.06,
  HEAL_PER_SEC: 1 / 3600,
  IDLE_MS: 20000
}

After 20 seconds without input, the meter subtracts HEAL_PER_SEC * healMultiplier * elapsedSeconds. At the default multiplier, that rate equals about 0.0278 percentage points per second. Dropping from 1 to 0.85 takes about nine minutes of healing, plus the idle delay; the strict below-0.85 check releases on a subsequent tick.

I calculate elapsed time from timestamps instead of subtracting a fixed amount per callback. Browser scheduling delays should change update cadence, not define the healing rate. These constants deserve attention during tuning because a 20-second recovery and a nine-minute recovery produce different user experiences.

MV3: block the next page of posts

A blur cannot stop someone from scrolling. At full damage, I ask the service worker to install dynamic declarativeNetRequest rules.

The content script sends a db-feedkill message with the desired state and hostname. In background.js, I generate rules from config.kill and call updateDynamicRules().

This condensed snippet follows the repository's precise-rule generation, including its six reserved IDs:

const RULE_IDS = [101, 102, 103, 104, 105, 106];

function preciseRules(config) {
  const rules = [];
  let id = 101;
  for (const filters of Object.values(config.kill || {})) {
    for (const urlFilter of filters) {
      if (id > 106) break;
      rules.push({
        id: id++,
        priority: 1,
        action: { type: 'block' },
        condition: {
          urlFilter,
          resourceTypes: ['xmlhttprequest']
        }
      });
    }
  }
  return rules;
}

async function setFeedBlocked(on, config) {
  await chrome.declarativeNetRequest.updateDynamicRules({
    removeRuleIds: RULE_IDS,
    addRules: on ? preciseRules(config) : []
  });
}

The extension declares storage, declarativeNetRequest, and alarms permissions in its MV3 manifest. Chrome performs the matching and blocking; I do not keep a JavaScript request listener alive to intercept each feed fetch.

The current filters include:

Reserved IDs    Endpoint family
101, 102        x.com/i/api/graphql and twitter.com/i/api/graphql
103             reddit.com/svc/shreddit/
104             instagram.com/graphql/query
105             youtube.com/youtubei/v1/reel/
106             linkedin.com/voyager/api/feed

Damage 0.995 -> install rules -> future matching requests fail
Damage <0.85 -> remove rules  -> later requests can proceed

These filters match endpoint families, not a verified feed operation within each GraphQL payload. A broad GraphQL filter can affect other features that share that URL. I also install the precise rules as a group, rather than limiting them to the tab that requested the block.

For an unknown host, the worker adds a generic rule for that host's XHR-class requests. That fallback extends coverage but can block unrelated API calls on the same site. The current host-hash ID allocation also permits collisions; it does not guarantee a unique ID for every hostname.

Chrome documents that dynamic rules persist across browser sessions and extension upgrades. Worker shutdown does not remove them. That persistence makes cleanup and recovery important: after healing, the extension must remove the rules, not just change a variable in the content script.

Blocking a request does not erase posts already in memory, stop an in-flight response, or force a site's feed component to retry. After removal, the site may need another user action to fetch again. The network gate controls future matching requests, not the entire application lifecycle.

Remote configuration without remote JavaScript

A feed extension depends on URLs and routing conventions that site owners can change. I keep those rules in config/sites.json: hostname regexes, active path prefixes, video path patterns, and network filters.

The worker refreshes configuration on install and browser startup, then through a six-hour alarm. It loads cached data first, validates fetched JSON, stores a version and fetch timestamp, and retains the cached or bundled configuration when fetching fails.

flowchart LR
    J[Repository config/sites.json] --> F[Service worker fetch]
    F --> V{Valid configuration?}
    V -->|Yes| C[Cache data and fetch timestamp in storage]
    V -->|No or offline| K[Keep cached or bundled configuration]
    C --> S[Content scripts update site matching]
    C --> N[Worker generates network rules]
    K --> S
    K --> N

I use the same broad remote-asset pattern as filter-list tools such as uBlock Origin: distribute changing declarative data apart from executable extension code. A maintainer can edit endpoint patterns without submitting a new executable package for each URL change.

The current file contains path and host rules, not arbitrary DOM selectors. The extension still ships its parsing and matching code in the package. Remote JSON does not grant permission to download and execute JavaScript; Chrome's remote-hosted-code guidance draws that distinction.

A six-hour alarm is a refresh cadence, not a delivery guarantee. A sleeping browser, lost network access, or an invalid update delays adoption. Remote configuration also cannot expand the six-rule budget in preciseRules(); adding a seventh filter to JSON requires a code change to avoid silent omission.

Inspect the real pipeline

The blur stage preserves the page structure while reducing readability.

The repository includes unit tests and a visual harness. These are commands for reproducing the development workflow, not a report that I ran them for this article:

npm install
npm test
python -m http.server 8377

Visual harness:
http://localhost:8377/test/harness.html

Unpacked extension:
chrome://extensions
  Developer mode
  Load unpacked
  Select the repository directory

The harness lets you drive damage thresholds through the rendering pipeline. To inspect network blocking, use the loaded extension on a supported site and watch the next matching request in DevTools. Inspect the service worker's dynamic rules as well: visible damage alone does not establish that Chrome installed a block.

I kept the central pieces separate: meter arithmetic in meter.js, input and rendering orchestration in content.js, declarative site data in config/sites.json, and rule installation in background.js. That separation lets a maintainer tune the discomfort curve without rewriting Chrome integration, or repair a changed feed endpoint without touching crack geometry.

The remaining engineering questions are concrete: choose a healing curve that matches the intended break length, reconcile simultaneous tab input, narrow shared API filters, and keep network-rule removal reliable after worker restarts. Those choices determine how the extension behaves after the screenshot, when someone stops scrolling and expects their page to recover.

Source: Ishan Naik / DoomBreaker.

Building a Terminal UI BitTorrent Client in Rust with Ratatui and Local Streaming

Ishan Naik — Wed, 07 Oct 2026 03:22:18 +0000

A video player reads a file in playback order. A BitTorrent peer can deliver whichever pieces it has. When I built Harbour, I had to connect those two access patterns without making the terminal wait for the swarm.

Harbour lets you search, download, and open a video in VLC or mpv from one terminal window. You can start playback before the download finishes. I use Rust 2024, Ratatui for rendering, Tokio for asynchronous work, and librqbit for the BitTorrent engine.

The demo uses the project's Creative Commons catalog, including Blender Foundation films. Use files you own or have permission to distribute. A protocol-neutral client does not grant distribution rights.

Keep rendering away from network work

I keep the engine adapter in src/engine/rqbit.rs. The queue and UI work with Harbour's types rather than librqbit handles. That boundary gives me one place to translate engine statistics, metadata, and errors.

For example, librqbit reports speeds in MiB/s. I convert those values in the adapter rather than asking each widget to remember the engine's units. I also represent an unavailable peer count with Option, because a paused torrent has no live peer statistics. Showing zero would confuse “no measurement” with “connected to no peers.”

I use Tokio tasks for asynchronous operations and event channels to bring results back to application state. Ratatui renders that state. I do not fetch metadata or wait for a peer inside a widget's draw function.

flowchart LR
    User[Keyboard and mouse input] --> App[Harbour application state]
    App --> Queue[Queue manager]
    Queue --> Adapter[librqbit adapter]
    Adapter --> Swarm[DHT, trackers, and peers]
    Adapter --> Events[Tokio event channels]
    Events --> App
    App --> UI[Ratatui views]
    App --> Source[HTTP Source adapter]
    Source --> Indexer[Local indexer API]
    Adapter --> HTTP[Loopback HTTP stream]
    HTTP --> Player[VLC or mpv]
    Queue --> Ledger[downloads.json]

I target a 30fps terminal render cadence. That number describes the UI schedule, not torrent throughput or video frame rate. A swarm can stop delivering data while you keep navigating the queue.

For this layout, I need separate clocks: network work follows socket readiness, playback follows the player's requests, and terminal rendering follows the UI cadence. Coupling those clocks would make a slow peer visible as input lag.

Watch mode: a file reader backed by incomplete data

BitTorrent downloads do not have to arrive in file order. A peer might supply a piece near the end before anyone supplies the next piece needed for playback. The engine must verify received pieces and make requested bytes available in the order the reader needs them.

For watch mode, I delegate this work to librqbit's HTTP API. In Harbour's adapter, stream_server() creates a Tokio listener with:

let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.ok()?;

The :0 asks the operating system for an available port. I bind to 127.0.0.1 rather than 0.0.0.0, so the playback endpoint does not listen on the machine's LAN interfaces. Loopback limits network exposure; it does not authenticate other processes running on the same machine.

I start the server on the first watch request and reuse it for later requests. Harbour constructs a URL with this shape:

http://127.0.0.1:<assigned-port>/torrents/<info-hash>/stream/<file-id>

I pass that URL to the external player. VLC or mpv then requests bytes over HTTP while Tokio workers continue contacting peers through DHT and trackers. The player uses its own demuxer, codecs, and playback buffers. I do not decode video inside the TUI.

sequenceDiagram
    autonumber
    participant U as User
    participant H as Harbour
    participant B as librqbit piece scheduler
    participant P as Swarm peers
    participant S as Localhost HTTP server
    participant V as VLC or mpv
    U->>H: Watch selected video
    H->>B: Resolve metadata and select file
    H->>S: Start or reuse 127.0.0.1 listener
    H->>V: Launch player with stream URL
    V->>S: HTTP request for file bytes
    S->>B: Read requested byte range
    B->>P: Prioritize pieces needed by reader
    P-->>B: Piece blocks
    B->>B: Verify and expose ordered bytes
    B-->>S: Contiguous bytes for requested range
    S-->>V: Stream response body
    V->>V: Buffer, demux, and decode
    Note over B,V: Missing required pieces can stall playback
    V->>S: Range request after seek
    S->>B: Read new offset and prioritize pieces

The “playback pipe” here means the HTTP response body. Harbour launches the player with a URL, rather than pushing video into its standard input.

Sequential reads still need random access

During normal playback, the player consumes bytes in sequence. On a seek, it can ask for a different range. Some media containers also require information outside the first bytes of the file.

A production endpoint therefore needs byte-range handling, including 206 Partial Content, Content-Range, and correct offsets. A stream that serves only the first byte onward can support a simple forward reader but cannot satisfy the player's full file-access contract.

I avoid building a second piece scheduler or range server in Harbour. The adapter uses librqbit::http_api::HttpApi, which keeps the HTTP reader connected to the engine's piece availability and prioritization.

I also wait for torrent metadata before returning the default video URL. The current adapter allows eight seconds and polls every 200ms. If metadata never arrives, or the torrent contains no recognized video file, Harbour can warn you before launching a player with an unusable URL.

For the default selection, I choose the largest recognized video file. A season pack may contain a small sample.mkv; alphabetical selection can send the player to that sample. File selection needs torrent metadata, not a guess based on the search result's display name.

The channel boundary behind an HTTP body

You can model the asynchronous handoff with a bounded Tokio channel. The producer reads ordered, verified bytes; the HTTP consumer drains the channel as the connection permits.

The following teaching example uses Axum's Body::from_stream, which supplies a body for the underlying Hyper stack. It illustrates the channel boundary, not Harbour's implementation. Harbour calls librqbit's HTTP API instead of adding this helper.

use std::io;

use axum::body::{Body, Bytes};
use futures_util::StreamExt;
use tokio::{io::AsyncRead, sync::mpsc};
use tokio_stream::wrappers::ReceiverStream;
use tokio_util::io::ReaderStream;

// Pass a torrent-backed reader that yields verified bytes in file order.
// Range parsing and response headers belong to the HTTP handler.
fn body_from_verified_reader<R>(reader: R) -> Body
where
    R: AsyncRead + Unpin + Send + 'static,
{
    let (tx, rx) = mpsc::channel::<Result<Bytes, io::Error>>(8);

    tokio::spawn(async move {
        let mut chunks = ReaderStream::with_capacity(reader, 64 * 1024);

        while let Some(chunk) = chunks.next().await {
            let failed = chunk.is_err();

            // A full channel suspends this producer. A disconnected
            // player drops the receiver and makes send return an error.
            if tx.send(chunk).await.is_err() || failed {
                break;
            }
        }
    });

    Body::from_stream(ReceiverStream::new(rx))
}

For a standalone example, include axum, futures-util, tokio, tokio-stream, and tokio-util; enable Tokio's runtime, I/O, and synchronization support and tokio-util's io feature. Those are example dependencies, not Harbour's direct dependency list.

I use eight channel slots to bound the number of chunks waiting at this handoff. With the reader's 64KiB capacity, that suggests roughly 512KiB of queued payload under typical chunking. It does not cap memory in the torrent engine, operating system, or player, and the slot count alone does not enforce a byte limit for arbitrary producers.

When the channel fills, send().await pauses this reader task rather than blocking an operating-system thread. When the player disconnects, a later send fails and the task exits. A producer waiting for a missing piece may need explicit cancellation to stop before that read completes; channel closure by itself cannot interrupt an unrelated pending read.

The reader must also propagate a missing-piece read failure as an error. Returning end-of-stream would tell the player that the file ended, which hides the transfer failure.

Keep search providers outside the client

I use the Stremio/Jackett addon paradigm for search: Harbour contains zero built-in scrapers and talks to a decoupled HTTP indexer. This describes the architectural split, not automatic compatibility with either project's wire protocol.

The default indexer URL is http://127.0.0.1:8765. The Harbour indexer contract defines three endpoints:

Endpoint	Client operation
`GET /search?q=...&exclude=...`	Retrieve results and omit user-disabled source IDs
`GET /magnet?hash=...&source=...`	Resolve a magnet if the result omitted one
`GET /health`	Check indexer connectivity

The indexer returns fields such as name, info_hash, size_bytes, seeders, and source. Harbour can merge and deduplicate results by info hash without knowing how the provider obtained them.

If you maintain a provider, you can change its parsing, credentials, or catalog independently of the Rust client. You also own another service: you must start it, configure its URL, and diagnose connection failures. Direct magnet and .torrent inputs do not need a search indexer.

I keep that distinction visible in the UI. An unavailable search provider should produce a search error, not imply that the BitTorrent engine has stopped working.

Recover a queue without erasing the evidence

A crash can leave two different problems: an interrupted state write and uncertainty about which transfers should restart. I handle those through separate mechanisms in src/persist.rs.

For downloads.json, I serialize the ledger, write a sibling temporary file, sync that file, and rename it over the destination. The current temporary path is downloads.json.tmp.

~/.harbour/
  downloads.json       saved queue ledger
  downloads.json.tmp   sibling file during a write
  boot.marker          interrupted-run detection
  cache/torrents/      cached .torrent metadata

I place the temporary file in the same directory so the replacement stays on one filesystem. I call sync_all() before the rename to reduce the chance that the replacement becomes visible before the file's contents reach storage.

Atomic replacement and power-loss durability have different guarantees. The implementation syncs the temporary file; it does not sync the parent directory after the rename. I would not claim that this sequence proves durability under every filesystem and power-loss scenario.

For recovery, I use boot.marker to detect an interrupted prior run. Harbour restores entries paused in Safe Mode, leaving you to resume them. On clean exit, I save the ledger before clearing the marker. If that save fails, I retain the marker rather than claiming a clean checkpoint.

I also preserve an unreadable ledger as downloads.json.corrupt rather than overwriting its contents with an empty queue. If the top-level JSON array parses but individual rows fail, I restore valid rows and report the skipped count. That distinction lets you recover usable entries while keeping the failure visible.

Piece verification belongs to the BitTorrent engine; ledger recovery belongs to Harbour. A valid JSON queue does not prove that the corresponding file bytes still exist or match their piece hashes.

Make terminal controls readable and reachable

I use Ratatui for the views and crossterm for terminal input and lifecycle. You can navigate with keys, click a search result, toggle sources, and choose VLC or mpv with the mouse. I keep both paths because selecting a player from a short list should not require learning another modal key sequence.

The theme loader supports the 67-token omp schema: semantic colors, named variables, and symbols. Harbour's views consume a subset, including accent, border, success, error, warning, selectedBg, and statusLineBg. Schema compatibility does not mean each Harbour screen uses all 67 tokens.

You can put a custom theme in ~/.harbour/themes/<name>.json. Semantic tokens let me style selection and failure states without putting RGB literals into individual widgets.

For color detection, I recognize COLORTERM=truecolor, COLORTERM=24bit, and a nonempty WT_SESSION. Otherwise, I use the 256-color path and quantize RGB values to ANSI palette indices. You can still read progress and errors in a terminal that lacks Truecolor support. Labels and selection remain necessary because color alone cannot convey state to every reader.

Try the client with a permitted file

Download the binary for your platform from GitHub Releases, install VLC or mpv, and start Harbour. To build from source:

git clone https://github.com/Ishannaik/harbour.git
cd harbour
cargo run

A Rust toolchain with 2024 edition support is required. For the Creative Commons demo workflow, search for sintel, select a result, and press Enter or w to watch. Choose your player when Harbour prompts you. Press Tab for the downloads view and ? for help. Configure your own local indexer when you want to search your own sources.

I keep the terminal client responsible for interaction, queue state, and recovery. I let librqbit manage peer traffic and verified file access, and I let VLC or mpv handle media playback. Those boundaries give me specific places to investigate a stalled watch session: metadata resolution, required piece availability, the loopback response, or the player. They also let me change a view without touching the code that decides which bytes are safe to serve.

Source: Ishannaik/harbour, by Ishan Naik.

Zero-Knowledge by Design: Client-Side AES-256 Encryption in SvelteKit

Ishan Naik — Wed, 07 Oct 2026 03:16:06 +0000

A developer pastes an API key into a conventional pastebin. The service receives the plaintext, writes it to a database, and returns a link. Anyone who can read that database can read the key: an administrator, an attacker with stolen credentials, or someone restoring a backup.

HTTPS protects the connection against passive network eavesdroppers. It does not prevent the service operator from reading the request after TLS termination. A pastebin that accepts plaintext has that access by design.

I built CloakBin around browser-side encryption. Senders encrypt before uploading. Recipients decrypt after downloading. The backend stores an encrypted content blob and operational metadata, without the content key or password.

The source repository uses SvelteKit and TypeScript. You can inspect the cryptographic boundary in src/lib/crypto.ts and the implementation details in docs/SECURITY-MODEL.md.

Separate the identifier from the secret

For a paste without password protection, the sender shares a link shaped like this:

https://cloakbin.com/p/abc#ENCRYPTION_KEY
                        |  |
                        |  +-- browser-side decryption key
                        +----- server-side paste identifier

Normal HTTP navigation:
GET /p/abc HTTP/1.1
Host: cloakbin.com

No #ENCRYPTION_KEY in the request target.

The recipient's browser requests /p/abc. Client-side JavaScript reads location.hash, imports the key, fetches the encrypted paste, and decrypts it.

RFC 3986, section 3.5 defines the fragment as a component that the client separates from the URI before dereferencing it. During normal HTTP navigation, browsers do not include the fragment in the request target. Browsers also omit fragments from the normal Referer header.

That rule does not stop application JavaScript from sending a fragment in a JSON body, an analytics event, or a custom header. Developers must keep the key out of those code paths. Putting a key after # gives the application a useful boundary, not permission to log location.href.

A query parameter would cross that boundary:

/p/abc?key=SECRET   -> server receives the key
/p/abc#SECRET       -> browser retains the fragment during navigation

Treat the full share link as a credential. Anyone who receives both the identifier and fragment key can decrypt the paste.

Follow the bytes from sender to recipient

sequenceDiagram
    participant A as Browser A (sender)
    participant S as CloakBin server
    participant D as Database
    participant B as Browser B (recipient)
    A->>A: Generate AES-256 key and fresh 96-bit IV
    A->>A: Compress plaintext and encrypt with AES-GCM
    A->>S: POST ciphertext frame and metadata
    S->>D: Store encrypted content
    S-->>A: Return paste ID
    A->>A: Build share URL with local fragment key
    A-->>B: Share /p/abc#key through chosen channel
    B->>S: Request /p/abc without fragment
    B->>B: Extract key from location.hash
    B->>S: Fetch encrypted paste by ID
    S->>D: Read encrypted content
    D-->>S: Ciphertext frame
    S-->>B: Ciphertext frame and metadata
    B->>B: Import key, authenticate, decrypt, decompress

The server needs the identifier to retrieve the paste. It does not need the key to perform that lookup.

Operators still observe metadata: content length, creation time, expiration, language selection, and access patterns. At the HTTP layer they can also observe IP addresses. In this article, “zero-knowledge” describes content confidentiality against a backend that follows the protocol. It does not claim anonymity or a formal zero-knowledge proof.

Encrypt with Web Crypto

CloakBin uses the browser's Web Crypto API, available through window.crypto.subtle. The implementation uses the shorter global crypto.subtle spelling.

For random-key pastes, the browser generates a 256-bit AES key and a fresh 12-byte initialization vector for each encryption. AES-GCM authenticates the encrypted bytes as well as encrypting them. With the 128-bit tag used here, Web Crypto appends 16 bytes of authentication data to its encryption output.

Never reuse an IV with the same AES-GCM key. Reuse can expose relationships between messages and undermine authentication. Use crypto.getRandomValues, not Math.random, for the 96-bit IV.

The following teaching example shows the AES-GCM core without CloakBin's compression or version framing. It runs in a browser secure context, such as HTTPS or localhost. It is not a replacement for the repository's serialized format.

type EncryptedPaste = {
  iv: Uint8Array;
  ciphertext: ArrayBuffer;
};

export async function generatePasteKey(): Promise<CryptoKey> {
  return window.crypto.subtle.generateKey(
    { name: 'AES-GCM', length: 256 },
    true, // Export the key for the share-link fragment.
    ['encrypt', 'decrypt']
  );
}

export async function encryptPaste(
  plaintext: string,
  key: CryptoKey
): Promise<EncryptedPaste> {
  const iv = window.crypto.getRandomValues(new Uint8Array(12));
  const bytes = new TextEncoder().encode(plaintext);
  const ciphertext = await window.crypto.subtle.encrypt(
    { name: 'AES-GCM', iv, tagLength: 128 },
    key,
    bytes
  );
  return { iv, ciphertext };
}

export async function decryptPaste(
  encrypted: EncryptedPaste,
  key: CryptoKey
): Promise<string> {
  const plaintext = await window.crypto.subtle.decrypt(
    {
      name: 'AES-GCM',
      iv: new Uint8Array(encrypted.iv),
      tagLength: 128
    },
    key,
    encrypted.ciphertext
  );
  return new TextDecoder('utf-8', { fatal: true }).decode(plaintext);
}

If someone changes the ciphertext or supplies the wrong key, subtle.decrypt rejects authentication. The caller should display a decryption error, without treating the bytes as plaintext or attempting to display unauthenticated content.

The IV does not need secrecy. The sender can store it alongside the ciphertext. The AES key does need secrecy.

Export only to the fragment

A raw AES-256 key contains 32 bytes. CloakBin exports those bytes and encodes them as base64url, replacing + and / with URL-safe characters and dropping padding.

export async function keyToFragment(key: CryptoKey): Promise<string> {
  const raw = new Uint8Array(
    await window.crypto.subtle.exportKey('raw', key)
  );
  return btoa(String.fromCharCode(...raw))
    .replace(/\+/g, '-')
    .replace(/\//g, '_')
    .replace(/=+$/, '');
}

export async function keyFromFragment(fragment: string): Promise<CryptoKey> {
  const base64 = fragment.replace(/-/g, '+').replace(/_/g, '/');
  const padded = base64 + '='.repeat((4 - (base64.length % 4)) % 4);
  const raw = Uint8Array.from(atob(padded), (char) => char.charCodeAt(0));
  if (raw.byteLength !== 32) throw new Error('Invalid AES-256 key length');
  return window.crypto.subtle.importKey(
    'raw', raw, { name: 'AES-GCM' }, false, ['decrypt']
  );
}

// After the upload returns an ID, run this in the sender's browser:
// const url = new URL(`/p/${id}`, window.location.origin);
// url.hash = await keyToFragment(key);
// Share url.href, without posting it back to the API.

Keep window and location.hash access in browser event handlers or Svelte's onMount. SvelteKit renders components on the server too; server rendering cannot read the recipient's fragment. The SvelteKit FAQ covers this browser-only execution boundary.

Serialize an encrypted frame, not plaintext JSON

CloakBin's current encoder compresses UTF-8 text with gzip before encryption. It then writes a versioned binary frame and base64-encodes that frame for storage:

Current v1 frame, before base64 encoding

Offset   Length     Field
0        2 bytes    "CB" magic: 0x43 0x42
2        1 byte     Version: 0x01
3        12 bytes   Random AES-GCM IV
15       remainder Encrypted gzip bytes + GCM authentication tag

The recipient decodes base64, reads the version and IV, authenticates and decrypts the encrypted bytes, then decompresses the result. CloakBin also accepts its older uncompressed format so existing pastes remain readable.

Base64 provides a transport encoding. Anyone can decode it to recover the frame, including its public IV. They still need the AES key to recover the compressed plaintext.

Compression reduces upload size for repetitive text, but an observer can still learn the encrypted length. Do not interpret compression or encryption as padding that hides message size.

Password protection: distinguish derivation from wrapping

CloakBin's current password mode derives the content-encryption key from the password. It does not derive a secondary wrapping key around a random content key.

That distinction matters when reviewing an implementation. In a wrapping design, developers would generate a random content key, derive a password-based key, and encrypt or wrap the content key with it. CloakBin instead uses the password-derived AES key to encrypt the paste itself.

The browser performs these steps:

Generate a random 16-byte salt.
Import the password as PBKDF2 key material.
Derive a 256-bit AES-GCM key with PBKDF2-HMAC-SHA-256 and 100,000 iterations.
Encrypt the paste with that key and a fresh 96-bit IV.
Upload the ciphertext and salt, without the password.

The recipient receives a link without a fragment key, enters the password, and repeats the derivation using the stored salt.

const material = await crypto.subtle.importKey(
  'raw', new TextEncoder().encode(password),
  'PBKDF2', false, ['deriveKey']
);

const key = await crypto.subtle.deriveKey(
  { name: 'PBKDF2', hash: 'SHA-256', salt, iterations: 100_000 },
  material,
  { name: 'AES-GCM', length: 256 },
  false,
  ['encrypt', 'decrypt']
);

An attacker with the salt and ciphertext can attempt offline password guesses. They can derive a candidate key and use GCM authentication to check it. The iteration count adds work per guess; it cannot give a short password the entropy of a random 256-bit key. Choose a long, unpredictable password and share it through a separate trusted channel when that separation matters.

Burn-after-read needs an atomic database operation

A developer who implements burn as a read followed by a delete creates a race:

Reader A: read document ---------- delete
Reader B:       read document ---------- delete
Result: both readers can obtain the same content.

CloakBin's MongoDB adapter uses a conditional findOneAndDelete through its model:

Model.findOneAndDelete({
  _id: id,
  burnAfterRead: true,
  expiresAt: { $gt: new Date() }
});

MongoDB performs this as one atomic find-and-delete operation, using the find-and-modify family of semantics. Developers do not need a separate read and a later delete for this single-document operation. Among concurrent matching burn operations, at most one caller receives the deleted document.

The UI asks the recipient to confirm before calling the burn endpoint. A normal page GET does not consume the paste. “First read” therefore means the first successful confirmed consumption, not the first page navigation or link preview. Review src/lib/db/adapters/mongodb.ts and the burn endpoint when checking that boundary.

Atomic consumption cannot guarantee that the recipient sees the plaintext. If the server deletes the document and the connection fails before delivery, the recipient may lose the paste. Nor can deletion erase a copy that a recipient saved, an operator retained, or a backup contains. Check the adapter you deploy: the repository's security model notes that some adapters lack a completed atomic burn implementation.

Verify the boundary in Chrome DevTools

Use a disposable marker such as cloakbin-network-check-12345, not a production API key. These steps describe a reproducible inspection, not a claim that I ran a live audit in this article.

Open Chrome DevTools, select Network, and enable Preserve log.
Create a paste without password protection. Select the outgoing POST /api/paste request and inspect Payload.
Check that content contains the base64 encrypted frame rather than your marker. Inspect the other fields: expiration, burn preference, and language metadata can remain readable. “Ciphertext-only content” does not mean that the entire JSON request contains no metadata.
Compare the generated address with the request URL. The share link includes #key; the upload should contain neither the key nor the full share link.
Open the share link in another tab with DevTools recording. Inspect the document request and paste API requests. Their request URLs should omit the fragment. Inspect headers and bodies too, checking for application code that might copy the key into a request.
Inspect the paste response. You should receive encrypted content, then see the browser display the decrypted marker after local processing.
Repeat with password protection. Expect a salt, no uploaded password, and a share link without a fragment key.

Do not publish a HAR file from a real secret-sharing session without reviewing it. Even if normal HTTP requests omit the fragment, debugging tools, screenshots, and copied browser addresses can expose sensitive material.

A Network inspection gives evidence about that interaction. It cannot prove that a future client build, a browser extension, or an injected script will preserve the same boundary.

The browser remains part of the trust model

A database dump gives an attacker ciphertext and metadata. With random-key pastes, it does not give them the fragment key. A passive network observer faces HTTPS plus application-layer encryption for paste contents.

An attacker who controls the JavaScript delivered to the sender or recipient has a different opportunity. They can change the client to upload plaintext, read location.hash, or capture a password before derivation. XSS and malicious browser extensions create similar risks. Browser-side encryption does not protect you from malicious code running inside the browser that handles the secret.

Deploy with HTTPS, review client dependencies, restrict script execution, and avoid analytics or logging that captures full URLs. Keep the share link out of issue trackers and support transcripts. Use short expiration when a paste has a short useful lifetime, and rotate credentials after sharing when your workflow permits it.

You can inspect CloakBin on GitHub or try cloakbin.com. Start your review at the browser crypto functions, follow the POST body into storage, and check the recipient's fragment handling. Those three places determine whether the server ever receives the secret it claims not to know.

Zero Cloud Storage: Building a P2P File Transfer App with WebRTC DataChannels and Cloudflare Workers

Ishan Naik — Wed, 07 Oct 2026 03:15:16 +0000

I built Warp so two people can transfer a file without uploading it to my infrastructure. The sender keeps the source file open. The receiver accepts the offer. Their browsers exchange the bytes through an encrypted WebRTC DataChannel.

That choice removes the hosted file store, its retention policy, and its bandwidth bill. It also leaves me with engineering work that an upload service would hide: NAT traversal, browser send queues, receiver storage quotas, and incomplete writes.

The MIT-licensed repository contains a React 19 and TypeScript frontend in web/, plus a Cloudflare Worker and Durable Object in server/. The production app uses Cloudflare's free tier. File size does not determine the signaling server's bandwidth use because the browsers carry the file traffic themselves.

The bill follows the file path

When you send a large archive through WeTransfer, Dropbox Transfer, or SendGB, you use a hosted transfer product. Those products offer different quotas, prices, and retention rules. I would not infer their internal storage providers from those limits or claim that they all use S3.

For a store-and-forward design, though, the cost model is concrete: the operator accepts the upload, retains the object, and serves downloads. An S3-style implementation needs object storage, upload handling, and a delivery path. If three recipients download a 10 GiB archive, the operator delivers 30 GiB of payload, apart from the sender's initial upload. Pricing depends on the provider, caching, region, and plan.

I chose a direct transfer path for Warp. The sender's connection carries the outbound traffic, and each recipient needs a live connection to the sender. I give up the ability to close the sending laptop and let someone download tomorrow.

Store-and-forward:
  sender -> hosted object -> recipient
                 |
                 +-> retention, quota, delivery costs

Warp:
  sender =================> recipient
         encrypted file bytes
     \                      /
      +---- signaling -----+
            SDP and ICE

This drawing describes an architecture comparison, not measured traffic from a benchmark.

Separate rendezvous from file transport

I split the system into a signaling plane and a data plane.

In the signaling plane, the browsers open WebSockets to the Cloudflare Worker. The Durable Object assigns a room code, tracks connected peers, and relays WebRTC offers, answers, and ICE candidates. The browsers need this rendezvous before they know how to reach each other.

In the data plane, each pair of browsers opens an RTCDataChannel. WebRTC carries SCTP messages over DTLS. The endpoints encrypt the traffic; the signaling service receives no file payload in this transfer path.

sequenceDiagram
    participant A as Sender browser
    participant W as Cloudflare Worker
    participant D as Signaling Durable Object
    participant B as Receiver browser
    participant S as Google STUN

    rect rgb(238, 242, 255)
        Note over A,B: Signaling phase over WebSockets
        A->>W: Create room
        W->>D: Upgrade and register socket
        D-->>A: Room code
        B->>W: Join room code
        W->>D: Register second socket
        A->>S: Discover public address
        B->>S: Discover public address
        A->>D: SDP offer and ICE candidates
        D->>B: Relay signaling
        B->>D: SDP answer and ICE candidates
        D->>A: Relay signaling
    end

    rect rgb(236, 253, 245)
        Note over A,B: Direct transfer phase: DTLS and SCTP
        A->>B: File offer over DataChannel
        B->>A: Accept
        A->>B: Binary file chunks
        B->>B: Write accepted bytes to receive sink
        A->>B: File end
    end

I keep the signaling socket available after connection setup. Warp uses it for membership changes, recovery, and an out-of-band cancel message. Calling the service an introducer does not mean the browser closes that socket once the channel opens.

The source boundaries help contributors trace a transfer:

Responsibility	Source path
Worker routing and room membership	`server/src/index.js`
Browser WebSocket client	`web/src/lib/warp/signaling.ts`
Peer connection and send pump	`web/src/lib/warp/peer.ts`
Control-frame types	`web/src/lib/warp/transfer.ts`
Receive sink accounting	`web/src/lib/warp/receiveController.ts`
OPFS worker and staging	`web/src/lib/warp/opfsStage.ts`
React orchestration	`web/src/lib/warp/useWarpTransfer.ts`

Hibernation changes how I keep room state

A connected WebSocket does not need to keep a Durable Object's JavaScript instance resident. With Cloudflare's WebSocket Hibernation API, I accept sockets through the Durable Object context. Cloudflare can evict an idle instance while retaining its connections, then reconstruct the instance when a message arrives.

That makes an ordinary in-memory Map a poor source of room membership. The constructor runs again after hibernation; the previous map no longer exists.

Warp attaches { ip, peerId, room } to each socket with serializeAttachment(). The server reconstructs membership from getWebSockets() and the socket attachments. The current implementation routes connections to one global Durable Object, which fits the project's present scale. Sharding would require another routing design.

I also need to distinguish zero cloud file storage from zero persistent metadata. Warp stores no file bytes on the server. The current server does write a reclaim:<code> record when the last socket leaves a room. That record reserves the rendezvous code for three minutes so disconnected peers can rejoin. It contains no transfer payload, and the server checks its expiry before reclaiming the room.

The rooms remain session-oriented. I have no object store of uploaded files and no long-lived download archive. Describing this version as having no persistent server state at all would conceal the reclaim record.

Hibernation avoids idle duration charges; it does not eliminate the cost accounting for incoming messages, execution, or storage operations. Warp runs at $0 within the free plan's allowances. Readers who self-host should check Cloudflare's current Durable Objects pricing before treating a hobby deployment as an unlimited service.

STUN-only gives me a defined failure mode

Warp configures public Google STUN endpoints:

const pc = new RTCPeerConnection({
  iceServers: [
    { urls: "stun:stun.l.google.com:19302" },
    { urls: "stun:stun1.l.google.com:19302" },
  ],
});

const channel = pc.createDataChannel("warp", { ordered: true });
channel.binaryType = "arraybuffer";

STUN lets the browsers discover server-reflexive addresses. ICE tests candidate pairs and attempts to establish a direct path. The STUN server handles address-discovery traffic, not the file stream.

I configure no TURN server. A TURN relay could help when direct traversal fails, but its operator would carry the file bytes and pay for that bandwidth. Adding one would change both Warp's economics and its file-path guarantee.

Some symmetric NAT combinations, UDP restrictions, firewalls, and network isolation policies prevent the browsers from connecting. Warp reports nat-failed when initial traversal fails. I do not promise that sharing a Wi-Fi network guarantees success: guest isolation or endpoint policy can still block the path.

The user can try another network. I accept that loss of connectivity coverage instead of adding a paid relay fallback.

Chunk size and queue size solve different problems

In peer.ts, Warp targets 256 KiB messages, meaning 256 * 1024 bytes. A DataChannel message is not an IP packet; the WebRTC stack can fragment it below the application layer.

I cap each message against the negotiated pc.sctp.maxMessageSize. Sending 256 KiB without checking the peer's limit risks a failed send(). The target also exceeds the 16 KB recommendation in RFC 8831, section 6.6, which addresses monopolization when message interleaving is unavailable. Warp's bulk-transfer workload favors fewer messages, but compatibility still constrains the final size.

The production sender reads the source in 4 MiB blocks and splits each block into smaller sends. That reduces asynchronous file-read calls compared with reading once per 256 KiB message.

Neither constant bounds the browser's send queue. For that, I inspect channel.bufferedAmount, which counts application bytes queued for transmission. Warp uses an 8 MiB high-water mark and a 1 MiB low-water mark. Before sending a chunk, I include its length in the high-water comparison.

Without that check, a fast disk can outpace the network. The browser queue grows until send() throws or memory pressure disrupts the tab. An arbitrary multi-gigabyte source should not require a multi-gigabyte JavaScript buffer.

A TypeScript sender loop for a React 19 app

The following example isolates the sender mechanism. It is explanatory code, not a copy of Warp's full engine: the production implementation also handles offers, cancellation, resume, and other protocol features. Call it from a React event handler after receiver acceptance and channel negotiation. Keep the connection object outside render state.

const TARGET_CHUNK = 256 * 1024;
const READ_BLOCK = 4 * 1024 * 1024;
const HIGH_WATER = 8 * 1024 * 1024;
const LOW_WATER = 1024 * 1024;

function waitForDrain(
  channel: RTCDataChannel,
  signal: AbortSignal,
): Promise<void> {
  return new Promise((resolve, reject) => {
    const cleanup = () => {
      channel.removeEventListener("bufferedamountlow", check);
      channel.removeEventListener("close", closed);
      channel.removeEventListener("error", closed);
      signal.removeEventListener("abort", aborted);
    };
    const closed = () => {
      cleanup();
      reject(new Error("DataChannel closed while draining"));
    };
    const aborted = () => {
      cleanup();
      reject(signal.reason ?? new DOMException("Aborted", "AbortError"));
    };
    const check = () => {
      if (signal.aborted) return aborted();
      if (channel.readyState !== "open") return closed();
      if (channel.bufferedAmount <= LOW_WATER) {
        cleanup();
        resolve();
      }
    };

    channel.addEventListener("bufferedamountlow", check);
    channel.addEventListener("close", closed);
    channel.addEventListener("error", closed);
    signal.addEventListener("abort", aborted, { once: true });
    check();
  });
}

export async function sendFileBytes(
  file: File,
  pc: RTCPeerConnection,
  channel: RTCDataChannel,
  signal: AbortSignal,
  onQueued: (bytes: number) => void,
): Promise<void> {
  if (channel.readyState !== "open" || !pc.sctp) {
    throw new Error("Negotiate an open SCTP channel first");
  }

  // A negotiated zero means no advertised message-size limit.
  const negotiated = pc.sctp.maxMessageSize;
  const chunkSize = negotiated === 0
    ? TARGET_CHUNK
    : Math.min(TARGET_CHUNK, negotiated);
  if (chunkSize < 1) throw new Error("Invalid SCTP message limit");

  channel.bufferedAmountLowThreshold = LOW_WATER;
  let queued = 0;

  for (let offset = 0; offset < file.size; offset += READ_BLOCK) {
    signal.throwIfAborted();
    const block = await file.slice(offset, offset + READ_BLOCK).arrayBuffer();

    for (let start = 0; start < block.byteLength; start += chunkSize) {
      const chunk = new Uint8Array(
        block, start, Math.min(chunkSize, block.byteLength - start),
      );
      while (channel.bufferedAmount + chunk.byteLength > HIGH_WATER) {
        await waitForDrain(channel, signal);
      }
      signal.throwIfAborted();
      if (channel.readyState !== "open") {
        throw new Error("DataChannel closed before send");
      }
      channel.send(chunk);
      queued += chunk.byteLength;
    }
    onQueued(queued);
  }
}

I register the event listeners before rechecking the buffer so a drain that happens near listener setup cannot strand the promise. I also reject on channel closure and abort, then remove all listeners. Waiting only for bufferedamountlow can leave a dead transfer suspended forever.

onQueued reports bytes handed to the channel, not bytes saved by the recipient. Finishing this loop does not prove receiver completion. The file protocol must finish its framing and the receiver must settle its writes before the UI claims success.

In React, I update progress once per read block rather than once per message. Keeping networking in TypeScript modules also lets me change queue policy without coupling it to component rendering.

Receive into a sink, then account for the write

A receiver that collects all chunks in an array and constructs one giant Blob can still exhaust memory even when the sender respects its own queue limit. I select a sink before accepting the file.

Warp's current browser support matrix describes three large-file paths. A batch reaches the large-file threshold when its total size or one file reaches 256 MiB.

Receiver capability	Large-file path
Matching native save picker	Stream to the user-selected file or folder
No selected native target, OPFS available	Stage in an origin-private file
OPFS unavailable	Stage Blob records in IndexedDB, subject to guards

For smaller transfers, Warp uses the in-memory tray. For origin storage, I check the browser's quota estimate before accepting. OPFS stores bytes on the receiver's device; it does not give the sender or my server a cloud copy.

Receiver backpressure has another boundary

The Streams API gives an application a way to await sink writes and propagate pressure through a pipeline. A DataChannel's message event does not provide the same interface as a ReadableStream: an async event listener does not stop later messages from arriving.

The diagram separates transport flow control from application write ordering. It does not claim that awaiting an OPFS write alone pauses a remote sender.

flowchart TD
    A[Sender file blocks] --> B[Check bufferedAmount plus next chunk]
    B --> C[RTCDataChannel over SCTP and DTLS]
    C --> D[Receiver message events]
    D --> E[Ordered receive sink queue]
    E --> F[Transfer ArrayBuffer to OPFS worker]
    F --> G[Write through sync access handle]
    G --> H[Acknowledge completed write]
    H --> I[Advance live-session bytesWritten]
    G --> J[Flush every 16 MiB and on close]
    J --> K[File-backed completed result]
    C -. SCTP transport flow control .-> B
    H -. Release current sink operation .-> E

Warp serializes sink operations and waits for worker acknowledgments. The OPFS worker receives an ArrayBuffer through a transfer list, writes through a FileSystemSyncAccessHandle, and handles short writes by continuing at the correct offset. I keep this work off the React thread.

A serialized write chain preserves order; it does not establish a bounded application backlog. If the receiver's disk stays slower than the connection, queued message buffers can still accumulate. Strict end-to-end memory bounds would require receiver credits, acknowledged write windows, or an equivalent bounded ingress mechanism. Sender bufferedAmount alone cannot promise that bound.

I also distinguish write acknowledgment from crash durability. Warp's OPFS worker flushes in 16 MiB batches and on close, rather than flushing each 256 KiB message. That avoids paying the flush cost for each chunk. After an unclean reload, I must reconcile the saved ledger offset with the actual surviving file length before resuming.

Within the running session, I advance bytesWritten after a successful write acknowledgment. If opening, writing, or closing fails, I poison the sink and report the failure. At file completion, I wait for pending writes and require the received byte count to equal the declared file size. Disk-full errors must not produce a completed transfer badge.

Encryption still has a trust boundary

DTLS protects the direct channel against network observers. In the intended deployment, the signaling service relays connection metadata and stays outside the payload path.

That leaves metadata exposure: the service can see connecting IP addresses, room codes, peer identifiers, timing, and SDP/ICE signaling. STUN operators also see the discovery requests. “No cloud file storage” does not mean anonymous communication.

I treat the short room code as a rendezvous token, not a durable password. Recipients should verify who joined and accept files they expect. Transport encryption also cannot protect a browser after someone compromises its JavaScript, or authenticate a human identity without another verification mechanism. A malicious signaling operator has a different threat model from a passive network observer.

The repository's threat model documents these boundaries. Keeping them visible matters more than attaching an unqualified privacy claim to the landing page.

Running Warp and reading the engine

For local development, start the frontend and signaling service in separate terminals:

pnpm install
pnpm dev:server
pnpm dev

The documented development ports are 8787 for signaling and 5173 for the web app. Configure the frontend's VITE_SIGNALING_URL for your signaling deployment; Vite embeds it at build time, so changing the deployed URL requires rebuilding the frontend.

I recommend reading peer.ts alongside opfsStage.ts. The sender has to respect a negotiated message limit and a local queue ceiling. The receiver has to preserve write order, survive storage failures, and distinguish acknowledged bytes from crash-persistent bytes. Those constraints remain whether the UI shows a single progress bar or a multi-device transfer tray.

Try Warp, or inspect the source on GitHub. For this design, the important trade-off is concrete: both peers stay online, direct ICE traversal must succeed, and the receiver needs enough local storage. In return, I do not operate a file warehouse or a relay carrying users' archives.

AI Coding Agents Are Leaking Your Secrets: Building a Local Pre-Commit DLP for Claude Code

Ishan Naik — Wed, 07 Oct 2026 03:15:10 +0000

You paste a .env file into Claude Code to debug a database connection. You remove the credentials from your next message, clean the repository, and rotate the database password. Your local conversation history still contains the original paste.

Claude Code keeps JSONL transcripts beneath ~/.claude/projects/. Codex keeps session JSONL beneath ~/.codex/sessions/. A process running as your user can read those files without asking either agent for permission.

I built AgentSweep to scan that history, report credential-shaped strings, and redact them without breaking the history format. I also added a pre-commit hook so developers can check this separate store of secrets before committing code.

The headline describes a credential exposure, not proof that your coding assistant has sent a key to an attacker. Developers create the exposure when they paste secrets or let an agent capture secret-bearing tool output. Attackers exploit the copy left on disk.

The credential store outside your repository

A repository scanner checks the files you stage or commit. Your agent's history lives elsewhere:

Developer home
|
+ .claude/
|  + projects/
|     + <encoded-project-path>/
|        + <session>.jsonl
|        + conversations/<session>.jsonl  (layout varies)
|
+ .codex/
|  + sessions/<year>/<month>/<day>/rollout-*.jsonl
|  + history.jsonl
|
+ workspace/
   + .env
   + .git/

Agent versions use different layouts. AgentSweep walks Claude Code's project trees for *.jsonl rather than assuming that a conversations/ directory exists. It also honors CLAUDE_CONFIG_DIR and CODEX_HOME, because a scan of the default home misses a developer's relocated profile.

Developers accumulate more than API keys in these records: PostgreSQL URLs with passwords, AWS access key IDs, GitHub tokens, private-key blocks, and wallet recovery phrases. An assistant response can repeat a credential from the prompt. Tool output can introduce another copy.

Cursor, Windsurf, and Aider keep local history too, but their storage formats differ. Aider uses Markdown history; other integrations use JSON or SQLite. Treating all coding assistants as JSONL producers would miss those stores. AgentSweep uses source adapters for discovery, string extraction, and format-specific redaction.

Rotating a key invalidates that credential at its provider. It does not remove its bytes from a transcript, backup, or filesystem snapshot. Cleaning Git history does not touch these directories either.

An install script runs with your filesystem access

An attacker who compromises a package can run code during installation. An npm postinstall script inherits the installing user's access. Attackers can use Python package build or installation execution paths for the same purpose; PyPI does not use npm's lifecycle-hook names.

Researchers have documented this class of theft. In Aikido's analysis of the compromised @bitwarden/cli@2026.4.0, the malicious preinstall payload targeted .env, cloud credentials, ~/.claude.json, and ~/.claude/mcp.json, among other files. That report establishes theft of AI-tool configuration credentials. It does not establish that this particular payload harvested conversation JSONL.

A transcript harvester needs the same filesystem access. The diagram below models that attack path:

flowchart TD
    D[Developer installs an npm dependency] --> P[Compromised package runs postinstall]
    P --> U[Payload runs as the developer's user]
    U --> H[Read files beneath ~/.claude/projects/]
    H --> J[Parse JSONL prompts and responses]
    J --> K[Extract tokens and database credentials]
    K --> E[Send credentials to attacker endpoint]
    E --> A[Attacker uses credentials that remain valid]

No exploit in JSONL parsing is necessary. The attacker reads an ordinary file. An owner-only permission mode helps against other local users, but it does not stop malware running under your account.

AgentSweep reduces the stored-history exposure. It cannot undo exfiltration, remove a provider's copy of a prompt, or stop malware from reading a live .env file.

Five stages, with an explicit write boundary

I separated discovery and detection from mutation. scan ends with a findings report. fix adds the redaction step, and developers still need to revoke exposed credentials themselves.

flowchart LR
    D[1. Discover: walk source history roots] --> S[2. Scan: Aho-Corasick and regex rules plus BIP-39]
    S --> F[3. Findings: masked report and locations]
    F --> C{Developer selects fix}
    C -->|No| X[Stop without modifying history]
    C -->|Yes, after safety checks| R[4. Redact: backup, temp write, validation, atomic replace]
    R --> K[5. Revocation guidance: provider URLs]

During scanning and redaction, AgentSweep makes zero network requests. It reads local history, performs local matching, and writes local results. Installation downloads packages, and opening a revocation URL uses your browser. The separate update command contacts PyPI. None of those actions belongs to the scan or redaction pipeline.

I chose that boundary because a credential-cleanup tool should not upload the material it inspects.

Discovery: extract strings without guessing the schema

For JSONL, a source adapter parses records and yields string values with their locations. The scanner can associate a finding with a file, physical line, and nested key path. The redactor can then reach that value in the parsed record.

The source layer matters for SQLite and Markdown too. A database adapter needs row-aware updates and an integrity check. A text adapter needs line-preserving replacement. Sharing detection rules does not require sharing a serialization strategy.

Scan: avoid running 207 patterns on every string

AgentSweep documents 207 regex rules, plus mnemonic detection. Applying each pattern to each prompt would repeat a lot of work on ordinary source code and prose.

I use Aho-Corasick pre-filtering to identify rule keywords in a shared pass. The matcher represents those keywords in a trie with failure links. After finding a keyword, the scanner selects the associated rules for regex evaluation.

A keyword hit does not prove that the string contains a credential. The regex still checks the shape and boundaries. Conversely, a rule without a safe keyword gate must remain eligible without a keyword hit. Otherwise the optimization would introduce false negatives.

For wallet phrases, membership in a word list is insufficient. The BIP-39 detector checks candidate lengths of 12, 15, 18, 21, or 24 words and verifies the checksum. That rejects many stretches of English prose that happen to contain mnemonic words. A valid checksum identifies a mnemonic-shaped value; it does not prove that someone funded the associated wallet.

Regex engines: keep compatibility when adding RE2

The default installation uses Python's re. Developers can install the optional native backend:

uv tool install 'agentsweep[fast]'

AgentSweep uses google-re2 for compatible patterns. RE2 avoids backtracking and provides linear-time matching for those expressions, which helps when developers paste large logs into a session.

RE2 does not support every Python regex construct. Lookarounds, Python-specific anchors, and Unicode semantics require care. AgentSweep retains the Python path for unsupported rules and semantic edge cases, including guarded non-ASCII inputs. It also retains that path for short strings and dense matches where native dispatch would not help.

I did not claim linear-time scanning for the entire mixed pipeline. Python fallback rules still use Python's engine.

The checked-in compatibility audit records 144 RE2 rules and 58 stdlib rules in a 202-rule snapshot. That snapshot predates the README's 207-rule count. Treat it as evidence for the routing design, not a current inventory. Rule counts need a version alongside them.

Start with a read-only report

AgentSweep requires Python 3.11 or newer. Install the CLI in an isolated tool environment, then select a source:

uv tool install agentsweep
agentsweep list-sources --detected
agentsweep scan --source claude-code --no-color
agentsweep scan --source codex --no-color
agentsweep scan --all --detected --json -o findings.json

The scan exit codes give scripts a small contract:

Exit code	Meaning
`0`	No findings
`1`	Findings exist
`2`	An error occurred

For a concrete report example, suppose a test transcript contains the AWS documentation sample key AKIAIOSFODNN7EXAMPLE. The following block illustrates the finding information, not an execution transcript or a byte-for-byte promise about terminal formatting:

source       claude-code
file         <project>/session.jsonl
line         1
rule         aws-access-key
preview      AKIA...MPLE
next action  Review the finding; revoke a real exposed key
scan status  Findings exist (exit 1)

Review the report without copying full credentials into an issue or another chat. A detector can recognize credential syntax without knowing whether the provider still accepts the value. AgentSweep stays offline, so it does not test key validity.

For a known false positive, use a narrow .agentsweepignore entry. Suppressing an entire provider rule makes future leaks from that provider invisible to the hook.

Redact JSON values, preserve parseable history

A raw substitution over serialized JSON can damage escaping or consume syntax outside the intended value. I redact string values in parsed records, then serialize the records again.

Consider this illustrative one-record transcript. The AWS key comes from a public documentation example, not a working credential.

Before:

{"type":"user","message":{"content":"AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE"}}

After:

{"type":"user","message":{"content":"AWS_ACCESS_KEY_ID=[REDACTED:aws-access-key]"}}

Value-level diff:

- AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
+ AWS_ACCESS_KEY_ID=[REDACTED:aws-access-key]

The redactor preserves the record's structure. Re-serialization can change whitespace, so I do not promise byte-for-byte identity outside the secret.

For production history, close the agent and allow the recent-write window to expire before fixing:

agentsweep fix --source claude-code --allow-production

In interactive mode, review the findings and type REDACT when prompted. The current alpha requires the production-root opt-in. Keep backups enabled.

Eight core write protections

I use eight core protections around this operation. The project also documents an alpha production gate and an audit log.

Protection	Engineering reason
Parse before replacement	Replace string values without editing JSON delimiters
Atomic replacement	Write a sibling temporary file, flush it with `fsync()`, then call `os.replace()`
Format-aware validation	Parse non-empty JSONL records and compare line counts before committing the replacement
Backup with no clobber	Create `.bak` by default with exclusive creation and mode `0600`
Path containment	Refuse targets outside the selected source's history roots
Symlink refusal	Refuse symlink targets rather than follow them into another file
Recent-write gate	Refuse files modified within the previous 60 seconds
Running-process gate	Refuse redaction when the relevant agent appears to be running

The fsync() and replacement sequence prevents a partial rewrite of the target during normal atomic-replace operation. It does not justify a blanket guarantee about storage hardware or power-loss durability on every filesystem.

The format check validates the rewritten content before os.replace() commits it. Describing that as validation after replacing the original would give readers the wrong failure model.

On POSIX, mode 0600 limits backup access to the owner. Windows uses ACLs with different semantics; do not interpret Python's mode argument as an equivalent Windows security boundary.

Developers can bypass the recent-write and process gates with --force. That flag does not bypass containment, symlink rejection, or invalid-content failures. Prefer closing the agent over overriding its concurrency checks.

Make history scanning a pre-commit checkpoint

Add the project's hook to .pre-commit-config.yaml:

repos:
  - repo: https://github.com/Ishannaik/agent-sweep
    rev: v0.1.9
    hooks:
      - id: agentsweep

The project's README uses this released tag in its example. Review release changes before choosing a newer pin.

Install the hook:

pre-commit install

The hook definition invokes:

agentsweep scan --all --detected

It sets pass_filenames: false and always_run: true. Developers therefore get one history scan per commit regardless of which files they staged. With no detected history root, the scan exits clean.

The hook blocks a commit when the detector finds a credential-shaped value. It does not redact anything during the commit. Developers review the report, revoke real exposed credentials, and run a separate fix operation.

This is a local data-loss-prevention checkpoint with limits. A developer can bypass Git hooks. Malware can read a transcript before the next commit. A clean result means the scanner found nothing within the selected sources and rules, not that the workstation contains no secrets.

Keep a staged-file secret scanner alongside it. The two scans inspect different stores.

Revoke the key, then remove the backup

A redaction changes your local history. The provider still accepts a live key until you revoke it.

AgentSweep includes provider-specific guidance. You can inspect a rule without scanning:

agentsweep explain stripe-live

For common findings, developers can review GitHub token settings, OpenAI API keys, or Anthropic API keys. AWS credentials require the appropriate IAM access-key workflow. AgentSweep prints guidance; it does not invoke those providers' APIs.

Backups contain the original plaintext. A same-user attacker who can read the transcript can also read its .bak file. After rotating the exposed credentials and confirming that you no longer need recovery, purge the backups:

agentsweep purge --source claude-code

If you need recovery before that point:

agentsweep undo --source claude-code

Undo restores the secret-bearing original. Purge removes the backup files; it does not promise secure erasure from SSD blocks, snapshots, or cloud backup systems.

My workflow is to avoid pasting secrets, scan existing history, review findings, revoke exposed keys, redact local copies, and remove recovery backups when I no longer need them. The pre-commit hook provides another checkpoint as new history accumulates.

You can inspect the source, detection rules, and safety code in Ishannaik/agent-sweep. If you report a missed credential format, share a synthetic example with the same shape. Do not attach the transcript you are trying to clean.

Written by Ishan Naik.

[Boost]

Ishan Naik — Sun, 11 Jan 2026 03:34:15 +0000

I Built a Pastebin Where Even I Can't Read Your Data

Ishan Naik ・ Jan 10

#security #privacy #webdev #opensource

My First saas

Ishan Naik — Sat, 10 Jan 2026 15:31:02 +0000

I Built a Pastebin Where Even I Can't Read Your Data

Ishan Naik ・ Jan 10

#security #privacy #webdev #opensource

[Boost]

Ishan Naik — Sat, 10 Jan 2026 10:44:58 +0000

I Built a Pastebin Where Even I Can't Read Your Data

Ishan Naik ・ Jan 10

#security #privacy #webdev #opensource