DEV Community: Gregory Mitchell

tinyimg - Image Manipulation on Cloudflare Workers

Gregory Mitchell — Tue, 08 Sep 2026 05:27:47 +0000

🏞️ tinyimg

Lightweight & fast image processing library for Cloudflare Workers

tinyimg decodes, transforms, draws on and re-encodes images inside a Worker, with no binding, no
subrequest and no per-transformation charge. It is freestanding C compiled to one wasm32 module,
wrapped by a TypeScript package.

Compared With Cloudflare Images

Both do the same job in different places. Images Transformations runs on Cloudflare's own pipeline and
bills per transformation. tinyimg runs in your Worker's isolate and bills as CPU time, which on the
Workers Paid plan is a resource the $5 subscription already includes 30 million milliseconds of.

	Cloudflare Images	tinyimg
Charge per transform	$0.50 / 1,000 unique, 5,000 free / mo	none
What you pay instead	nothing else	Worker CPU time
Billing granularity	unique source and flags, once per month	every invocation that is not cached
Subrequest or binding	required	none
AVIF output	yes	no
Runs on Workers Free	5,000 transforms / mo	sources up to roughly 2 MP
Raw pixel access	no	yes
Shapes and gradients	no	yes
Text	one string, one font, one size	layout, wrapping, alignment, metrics

Cost

Past the included CPU, Workers bills $0.02 per million CPU milliseconds, so a transformation costs
its own compute multiplied by that. Three routes to the same 800 px page:

Route	`effort`	Compute	Per million	Within the included CPU
800 px WebP	fancy	41.6 ms	$0.83	721,000
800 px WebP	fast	33.4 ms	$0.67	898,000
800 px JPEG	either	20.8 ms	$0.42	1,442,000

Against $500 per million for Images at $0.50 per 1,000. The absolute figures are small whichever
route you take. What the spread buys is CPU headroom, and headroom is what the Free plan rations.

Images bills a unique source and flag combination once per calendar month however often it is
served, so a small set of derivatives under heavy traffic is already cheap there. tinyimg charges for
every invocation that runs, so put Workers Cache
in front of it and a hit costs no CPU at all. tinyimg wins on many distinct derivatives, Images wins
on few you have not cached.

Speed

Median wall clock in bun on darwin-arm64 over sf-24.jpg at 1835x1032. This is not Worker CPU time
on Cloudflare's hardware, so profile your own images.

Request	`effort: 'fancy'`	`effort: 'fast'`
200 px cover, JPEG q80	7.2 ms	6.9 ms
200 px cover, WebP q80	8.3 ms	7.7 ms
400 px cover, JPEG q80	11.7 ms	11.8 ms
400 px cover, WebP q80	17.2 ms	14.9 ms
800 px cover, JPEG q80	20.8 ms	20.8 ms
800 px cover, WebP q80	41.6 ms	33.4 ms

effort moves WebP at every size and leaves JPEG output flat, because the WebP encoder has a 4x4
prediction search to bound and the JPEG encoder has no equivalent.

JPEG's own lever is on the decode side, and a thumbnail cannot show it. Replicating chroma instead
of filtering it is worth 1.11x to 1.25x on a full decode, but the saving scales with output samples
while a reduced request's cost is dominated by the entropy decode, which the source fixes. On a
4:2:0 source it measures 1.00x at 200 px and 1.07x at the source's own extent. sf-24.jpg cannot
show it at any size, being 4:4:4 with no chroma to upsample.

A request the source already satisfies is 0.01 ms and a plan decision with no pixels decoded is
under 0.1 ms; neither depends on effort.

The Workers Free plan allows 10 ms of CPU per request and does not let a caller pay for more, so a
request either fits or fails. Workers Paid defaults to 30 seconds, raised to 5 minutes with
limits.cpu_ms, and nothing above comes close to it.

What fits Free is decided by the source, not by the size you ask for. Every row below produces
the same 200 px thumbnail from the same eighth-scale decode, and every one of them decodes 1.57% of
its source's samples. The spread is the entropy decode, which no output size can reduce.

Source	Megapixels	200 px wide, JPEG
320x180	0.06	2.20 ms
1835x1032	1.89	6.80 ms
1920x1250	2.40	15.86 ms
5000x4000	20.00	25.41 ms

So roughly two megapixels is the Free ceiling for a synchronous transformation, whatever the output
size. Past that the artifact has to be computed once and cached; see Caching.

Decode is 1.2x to 2.1x behind libjpeg, libpng and libwebp, which have SIMD implementations of their
hot kernels and tinyimg has none. WebP and PNG encode are slower still.
TECHNICAL_REPORT.md has
the per-stage profile and the comparison against @jsquash.

Gaps

No AVIF output. Images serves AVIF through format=auto. tinyimg parses the container and reports its dimensions, and encodes WebP instead, which lands 25-35% below JPEG at matched quality. See Out of Scope.
No animation. Both decode a first frame; neither re-times or composes one.
You own the caching. Images caches derivatives at the edge as a product feature. tinyimg gives you the key and leaves the cache to you; see Caching.

What tinyimg Adds

Images covers resize, fit, gravity, the standard adjustments, image overlays with Porter-Duff
compositing, and a rasterized text string. Past that:

A drawing surface. Lines, rectangles, rounded rectangles, circles, ellipses, polygons with both fill rules, linear and radial gradients, and a display list with a transform matrix stack.
Text as layout. Wrapping, alignment, text boxes and measurement, against Images' single styled string.
Raw pixels. decode and Image.pixels hand back samples, so anything not in the operation set is still reachable.
Effects and warps. Sobel, emboss, morphology, median, dither, halftone, duotone, split-tone, color blindness simulation, curves, channel mixer, shear, perspective, barrel and swirl.
Face boxes, not just face gravity. detectFaces returns rectangles, and tiny_image_blur_faces and tiny_image_pixelate_faces act on them.
Analysis. Histogram, dominant color, palette extraction and a perceptual hash.

The chainable Image class covers the transformation set. Drawing, text, the effects and the
analysis helpers are module exports, reached through tinyimg.exports with the same names the
headers use.

Install

npm install @gmitch215/tinyimg

bun add @gmitch215/tinyimg

Getting Started

The module has to arrive already compiled. workerd refuses WebAssembly.Module(bytes), so importing
the wasm file is what makes it work: the runtime compiles it at worker startup.

import wasm from '@gmitch215/tinyimg/tinyimg.wasm';
import { TinyImgModule, transform } from '@gmitch215/tinyimg';

const tinyimg = TinyImgModule.load(wasm);

export default {
    async fetch(request: Request): Promise<Response> {
        const source = await fetch('https://example.com/photo.jpg');

        const thumb = await transform(tinyimg, source, {
            width: 400,
            height: 400,
            fit: 'cover',
            format: 'webp',
            quality: 80
        });

        return thumb.response({ 'cache-control': 'public, max-age=86400' });
    }
};

Under node, bun or a browser, compile from bytes instead:

import { readFileSync } from 'node:fs';
import { TinyImgModule } from '@gmitch215/tinyimg';

const tinyimg = await TinyImgModule.loadBytes(readFileSync('tinyimg.wasm'));

Input accepts a Uint8Array, an ArrayBuffer, a Blob, a Response or a ReadableStream. Results
carry .bytes(), .blob(), .response() and .dataUrl().

Transformations

transform takes one option object. The names mirror Cloudflare Images' own parameters.

Option	Type	What it does
`width`, `height`	`number`	Target extent. One alone keeps the aspect ratio.
`fit`	`Fit`	How an aspect mismatch is absorbed. Read when both extents are given.
`gravity`	`Gravity`	Which part a crop keeps, or where a pad puts the image.
`filter`	`ResampleFilter`	Weights the resample reads through.
`crop`	`Rect`	Source rectangle, taken before anything else.
`dpr`	`number`	Multiplies `width` and `height`.
`rotate`	`0 \	90 \
{% raw %}`flip`	`'horizontal' \	'vertical' \
{% raw %}`brightness`, `contrast`, `saturation`, `gamma`	`number`	1 is unchanged.
`hue`	`number`	Degrees.
`grayscale`, `invert`	`boolean`
`blur`	`number`	Gaussian radius in pixels.
`sharpen`	`number`	Unsharp mask amount.
`trim`	`boolean \	number`
`background`	`Color`	Fills whatever a pad or a rotation leaves empty.
`format`	`ImageFormat`	Container to encode as. Defaults to the source's own.
`quality`	`number`	1 through 100, for a lossy format.
`lossless`, `progressive`	`boolean`	Where the format has the mode.
`metadata`	`'keep' \	'none'`

The options apply in a fixed order, exported as TRANSFORM_ORDER: crop, resize or fit, rotate, flip,
the color adjustments, blur, sharpen, trim. An option object has no order of its own, so two callers
writing the same keys get the same image.

Fit Modes

Mode	Absorbs the mismatch by	Scale may
`scale-down`	leaving it	only fall
`contain`	leaving it	rise or fall
`scale-up`	leaving it	only rise
`cover`	cropping	rise or fall
`crop`	cropping	only fall
`fill`	cropping	only rise
`aspect-crop`	cropping	neither
`aspect-cover`	cropping to the target's shape	neither
`pad`	padding	rise or fall
`aspect-contain`	padding to the target's shape	neither
`stretch`	distorting	rise or fall

Gravity

The nine fixed positions are center, north, south, west, east, north-west, north-east,
south-west and south-east.

Two are computed from the image. auto weights every tile by local detail and centers on the
centroid, so a photograph with one sharp subject on a soft background focuses on the subject. face
runs the detector and centers on what it finds, falling back to auto when no cascade is loaded or
nothing is found.

Chaining

Image is the same planner with a method per operation, for when you want two encodings of one
transformation or an operation the option object does not cover.

import { Image } from '@gmitch215/tinyimg';

using image = await Image.open(tinyimg, request.body);

image.crop(400, 200, 900, 600).resize(300, 200).brightness(1.2).sharpen(1);

const webp = await image.bytes('webp', { quality: 80 });
const png = await image.bytes('png');

The handle lives in the module's memory, so using is the shortest correct way to hold one. Without
it, call dispose() in a finally. Encoding does not consume the plan.

pixels() hands back the raw samples for a caller who wants them rather than a container.

The Planner

Nothing runs until the output is asked for. Operations append to a fixed-capacity list, and the plan
runs once:

image.crop(2000, 1500, 500, 500).resize(100, 100);
image.brightness(1.2).contrast(1.1).saturation(0.8).gamma(2.2);

The output needs a 500x500 source rectangle out of 16 megapixels, so the decoder is asked for that rectangle and nothing else.
A 100x100 output from a 500x500 source needs no detail above a quarter, so JPEG decodes at 1/4 through a reduced IDCT.
Brightness, contrast and gamma become one 256-entry table; saturation becomes one matrix.
Six traversals become one pass over 10,000 output pixels.
An added brightness(1.0) never runs.

decide() reports all of it without producing the image:

using image = await Image.open(tinyimg, source);
image.crop(400, 200, 900, 600).resize(300, 200);

const decided = image.decide();
// { region: { x: 400, y: 200, width: 900, height: 600 }, scale: 4,
//   decoded: { width: 225, height: 150 }, output: { width: 300, height: 200, channels: 3 },
//   eliminated: 0, collapsed: 0, colorStages: 0, passes: 1,
//   kernels: ['region', 'scaled', 'resample'] }

On that chain the planner is worth 3.63x against running the same operations one pass each.

Codec Support

Format	Decode	Encode
PNG	8 and 16 bit, gray/palette/truecolor with and without alpha, Adam7	hash-chain LZ77, static and dynamic Huffman, the five filters
JPEG	baseline and progressive, 4:4:4 / 4:2:2 / 4:2:0, CMYK and YCCK, restart markers	quality-scaled tables, optimized Huffman, progressive scan script
WebP	VP8 lossy and VP8L lossless	both modes
GIF	LZW, local and global palettes, interlace, transparency	median-cut palette with Floyd-Steinberg dithering
TIFF	strips, uncompressed / PackBits / LZW / Deflate, both byte orders	uncompressed and PackBits
BMP	uncompressed and RLE8	uncompressed
AVIF, HEIF	container only; `probe` answers and decode reports a specific error	no

JPEG carries true DCT-domain scaled decode at 1/2, 1/4 and 1/8, and region decode that Huffman-scans
past blocks outside the box without transforming them. PNG, GIF, TIFF and BMP row-skip and
column-skip.

probe reads headers only, for every format including the ones the library cannot decode:

const info = await tinyimg.probe(source);
// { width, height, frames, format, channels, bitDepth, hasAlpha, progressive }

Drawing

Pixels, lines with thickness, rectangles, rounded rectangles, circles, ellipses, and polygons filled
by scanline with either the even-odd or the nonzero rule. Linear and radial gradients, borders,
per-channel color replacement, and image compositing with opacity, tiling and edge offsets.

Compositing carries the CSS separable blend modes: multiply, screen, overlay, darken, lighten,
hard-light, soft-light, difference, exclusion, add and subtract, composed in premultiplied form so a
stack of partly transparent layers ends up as transparent as it should be.

A display list keeps shapes symbolic behind a 2x3 affine stack until one rasterization, and drops a
shape that falls outside the target or that a later opaque shape completely covers.

Effects

Roughly ninety, reaching the planner through three generic operations, so they compose into one
matrix and one table wherever they can.

Tone and color. negate, grayscale, black and white, colorize, tint, posterize, threshold, solarize, duotone, split-tone, exposure, fill light, temperature and tint white balance, vibrance, levels, curves from control points, color balance by band, channel mixer, per-channel gain, colorblind simulation and assist, and nine named presets.
Spatial. unsharp mask, clarity, sobel, emboss, pixelate, median despeckle, morphology, outline, motion / radial / zoom blur, tilt-shift, region blur, drop shadow, glow, gradient fade, noise, film grain, ordered dither, halftone, chromatic aberration, scanlines.
Auto-correction. auto brightness, contrast, color, levels and gamma; improve; shadow and highlight recovery; dehaze by dark-channel prior.
Geometry. shear, quad and perspective distort by inverse homography, arc warp, barrel and pincushion, swirl, polar, corner radius.
Analysis. histogram, dominant color, palette extraction, average color, and a 64-bit perceptual hash with a Hamming-distance helper.

Text

TrueType and OpenType with glyf outlines, plus PSF and BDF bitmap faces, dispatched from the magic
bytes. Quadratic flattening and a scanline fill with four vertical subsamples and exact horizontal
coverage.

const font = await env.BLOBS.get('fonts/DejaVuSans.ttf');
if (font) await tinyimg.loadBlob('font', 'sans', font.body);

tiny_image_draw_text, tiny_image_draw_text_box with wrapping and alignment, and tiny_text_measure
share one layout walk, so measuring and then drawing at the measured position lands where the
measurement said. Kern pairs are applied when the face carries a kern table.

100 characters at 16 px cost 0.156 ms.

Face Detection

An LBP cascade over an integral image, multi-scale, with union-find grouping. The cascades are
OpenCV's lbpcascade_frontalface_improved.xml and lbpcascade_profileface.xml.

The module carries no cascade data and no XML parser, so a cascade arrives as bytes in a packed form
that scripts/fixtures.ts builds from the OpenCV source: 7.4 kB for the frontal cascade against 54 kB
of XML. loadBlob rejects one still in XML. Both packed cascades are published, and
bun run blobs rebuilds them if you would rather host your own:

const frontal = await fetch('https://cdn.gmitch215.dev/tinyimg/cascades/lbp-frontalface.bin');
const profile = await fetch('https://cdn.gmitch215.dev/tinyimg/cascades/lbp-profileface.bin');

await tinyimg.loadBlob('cascade', 'frontal', await frontal.arrayBuffer());
await tinyimg.loadBlob('cascade', 'profile', await profile.arrayBuffer());

const faces = await tinyimg.detectFaces(source);
// [{ x, y, width, height, neighbors }]

Every resident cascade runs and the results are grouped together, so a frontal and a profile cascade
find both kinds of face and a face that fires both is one box. Detections match OpenCV's own detector
within a pixel on identical pixels.

Feeds gravity: 'face'. With no cascade loaded, detectFaces reports a TinyImgBlobError and
gravity: 'face' falls back to auto.

Color Management

ICC matrix-and-TRC profiles: the rXYZ / gXYZ / bXYZ primaries, curv and parametric para
tone curves, and Bradford chromatic adaptation folded into the matrix. Conversion between a tagged
profile and sRGB agrees with ImageMagick at 49 dB.

Reading the dB Figures

Every accuracy number here and in the technical report is PSNR against a stated reference:
10 * log10(255^2 / MSE), where the mean squared error runs over every channel sample of both
images. It is a log scale, so 6 dB is one bit of precision and each 10 dB is a tenfold drop in
squared error. Higher is closer, and infinity means the two images are byte-identical.

Where the thresholds fall, for 8-bit images:

PSNR	What it looks like
above 50 dB	below one level of quantization; no viewer can distinguish the two
40 to 50 dB	indistinguishable in normal viewing, and separable in a difference blend
30 to 40 dB	artifacts findable if you look for them, around the quality of a JPEG at q75-85
below 30 dB	visible on inspection

Those bands are the conventional reading of the scale rather than something measured here, and PSNR
scores per-sample error without regard to where the error sits. A few badly wrong pixels and a faint
haze across the whole frame can score the same while looking nothing alike, which is why the codec
tests assert a floor per fixture instead of one number for the library. The floors that matter are
the ones the comparison is stated at: 49 dB for an ICC conversion is a rounding difference, and the
24 dB floor on a glyph shape is a hinting difference measured against FreeType.

LUT-based A2B and B2A profiles, which is mostly CMYK printer profiles, are rejected with a specific
error rather than approximated. The matrix and TRC path covers sRGB, Display P3, Adobe RGB and
Rec.2020, the profiles web images carry.

Budget and Effort

Three things let a caller work inside a CPU limit instead of discovering it.

A request the source already satisfies costs a header read. transform compares the request
against the source's header first, and hands the original bytes back when there is nothing to do. A
600 px bound on a 400 px WebP decodes nothing.

effort: 'fast' bounds the work rather than the quality. Quality says what the output should
look like; effort says how hard to work to get there. It applies to the decode, the resize and the
encode, and each part gives up something measured:

Stage	What `fast` does	Speed	Quality
Decode	WebP skips deblocking	1.53x	46.8 dB
Decode	JPEG replicates chroma instead of filtering	1.11x to 1.25x	43.6 to 59.5 dB
Resize	Bilinear instead of Catmull-Rom, enlarging	3.2x	45.7 dB
Encode	WebP bounds the 4x4 prediction search	1.18x to 1.45x	within 0.05 dB

Only a lossy format has anything to trade. A lossless one defines its pixels exactly, so every
step is needed to produce them: PNG, GIF, TIFF and lossless WebP decode identically at either
effort, and so does a 4:4:4 JPEG, which has no chroma to upsample. A reduction also keeps its
filter, because an area average is already both the cheapest and the right answer; only enlarging
has a filter to step down.

A filter you name is never substituted, and neither is a format. Effort decides what the library
left open, not what you asked for.

End to end, on requests through the whole pipeline:

Request	`fancy`	`fast`
200 px, WebP source, WebP out	18.5 ms	13.5 ms	1.38x
800 px, WebP source, WebP out	54.6 ms	42.2 ms	1.29x
800 px, JPEG source, WebP out	42.2 ms	34.0 ms	1.24x
800 px, JPEG source, JPEG out	21.6 ms	21.5 ms	1.01x

A WebP source gains most, because it is the only one where both the decode and the encode have
something to give. The last row is the contract working rather than a failure: a 4:4:4 JPEG decoded
and re-encoded as JPEG has no deblocking pass, no chroma to replicate and no prediction search, so
there is nothing for effort to spend.

Encoded size can go either way under fast, because the per-subblock choice minimizes prediction
error rather than rate: a diagonal mode can win on error and then cost more bits to code. Flat-color
illustrations pay the most, and hard diagonal edges are what those modes exist for.

decide().estimateMs prices a plan before it runs, and budgetMs acts on it. The encoders differ
by roughly a factor of five per sample, so format: 'auto' with a budget takes WebP when it fits and
JPEG when it does not:

const result = await transform(tinyimg, source, {
    width: 400,
    format: 'auto',
    budgetMs: 7,
    effort: 'fast'
});

result.format; // 'webp' if it fits inside 7 ms, otherwise 'jpeg'

A format you name is never substituted, however far over budget it is. The estimate is accurate to
about 20% on the machine its rates were measured on, so give a budget below the limit rather than at
it, and use measure when you need what a request cost.

Caching

A cache hit costs no CPU at all, which is how a request too expensive to serve synchronously still
gets served: it is computed once. artifactKey builds the canonical key, identifying the source by
the hash of its bytes so the same picture from two places is one artifact:

import { artifactKey, transform } from '@gmitch215/tinyimg';

const key = await artifactKey(source, options);
const hit = await caches.default.match(key);

if (hit) return hit;

const out = await transform(tinyimg, source, options);
const response = out.response({ 'cache-control': 'public, max-age=31536000, immutable' });

ctx.waitUntil(caches.default.put(key, response.clone()));
return response;

Work Counters

Every reduction in this library is a claim that some work does not happen, and a label is not
evidence. measure returns what the module did:

const { work } = await tinyimg.measure(() => transform(tinyimg, source, { width: 200 }));

work.samplesPerTransform; // 1 at an eighth scale, 4 at a quarter, 64 at full
work.decodedSamples / work.sourceSamples; // what the reduction was worth
work.filtered; // macroblocks a region did not skip

samplesPerTransform is the one to read for a scaled decode: a decode transforming whole blocks and
averaging them away reads 64 whatever its name is.

Blobs

Three kinds of data load at runtime rather than shipping in the module: fonts, ICC profiles and
detection cascades. loadBlob takes bytes from anywhere, so there are three ways to deliver them and
no code change between them.

The prebuilt set is published at https://cdn.gmitch215.dev/tinyimg/, with
https://cdn.gmitch215.xyz/tinyimg/ and https://cdn.gmitch215.blog/tinyimg/ as mirrors.
blobs.json sits at that prefix and each entry's path resolves against it, so one URL is enough to
find the rest. A plain fetch needs no binding and costs one subrequest:

const font = await fetch('https://cdn.gmitch215.dev/tinyimg/fonts/DejaVuSans.ttf');
await tinyimg.loadBlob('font', 'sans', await font.arrayBuffer());

A binding costs the same one subrequest and keeps the bytes on your own account. BLOBS below is an
R2 bucket you have uploaded blobs/ to, and an Assets binding works the same way:

const cascade = await env.BLOBS.get('cascades/lbp-frontalface.bin');
if (cascade) await tinyimg.loadBlob('cascade', 'frontal', cascade.body);

{
    "r2_buckets": [{ "binding": "BLOBS", "bucket_name": "tinyimg-blobs" }]
}

Or bundle one as a wrangler Data module, which costs bundle bytes and no latency:

import cascade from './lbp-frontalface.bin';
await tinyimg.loadBlob('cascade', 'frontal', cascade);

Eight blobs can be resident at once. freeBlob releases one and freeBlobs releases all. A cascade
is parsed at load, so a bad one fails at startup instead of becoming a search that finds nothing.

Error Handling

Every failure carries the module's own error code and its stable name, so a caller branches on the
code rather than on a message.

import { TinyImgBlobError, TinyImgFormatError } from '@gmitch215/tinyimg';

try {
    return (await transform(tinyimg, source, { width: 400 })).response();
} catch (error) {
    if (error instanceof TinyImgFormatError) return new Response('unsupported image', { status: 415 });
    if (error instanceof TinyImgBlobError) return new Response('font not loaded', { status: 500 });

    throw error;
}

Class	Covers
`TinyImgArgumentError`	a null argument, a value out of range, a rectangle outside the image
`TinyImgFormatError`	an unrecognized format, or a variant this build cannot read
`TinyImgDataError`	a malformed, truncated or inconsistent bitstream
`TinyImgMemoryError`	the allocator refused a request that was within budget
`TinyImgTooLargeError`	the image is past the budget, so a smaller decode is the remedy
`TinyImgBlobError`	a font, profile or cascade nobody loaded
`TinyImgPlanError`	the plan is full, or holds an operation it cannot combine
`TinyImgLoadError`	the module is not tinyimg, or its ABI is one this wrapper does not know

Size

Small size is the primary goal, ahead of speed and then memory. The published package is 138.7 kB,
of which the wasm module is 90.4 kB gzipped and the wrapper is 7.8 kB. bun run size prints the
breakdown.

Every codec can be compiled out, so a caller who only handles PNG can link a module with nothing
else in it. --gc-sections then drops the implementation along with its registry entry.

cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=cmake/wasm32.cmake \
  -DCMAKE_C_FLAGS="-DTINYIMG_NO_WEBP -DTINYIMG_NO_TIFF -DTINYIMG_NO_GIF"
cmake --build build

That build is 65.4 kB gzipped against 90.4, and tinyimg.features reports the three as absent, so a
caller can check before offering a format rather than calling and handling a failure.

Build it into its own directory and bin/tinyimg.wasm is still where it lands, because that path is
absolute in CMakeLists.txt. Run bun run build:wasm afterwards to put the full module back.

Platform Limits

The module must arrive compiled. workerd refuses WebAssembly.Module(bytes) with "Wasm code generation disallowed by embedder". Import the .wasm file; loadBytes is for node, bun and the browser and throws on Workers.
The Workers Free plan allows 10 ms of CPU per request, which is not configurable and is below the cost of most transformations; see Speed. Workers Paid defaults to 30 seconds and goes to 5 minutes with limits.cpu_ms. A Worker over the limit returns error 1102.
32 MiB per decoded image, inside 64 MiB of linear memory, with a 16 megapixel ceiling on top that only grayscale reaches. The byte cap is the one that binds, because an allocation is bytes: it allows 11.2 megapixels of RGB and 8.4 of RGBA. Past either, the library reports TinyImgTooLargeError, whose remedy is a smaller decode rather than more memory. A larger source is still usable; that is what a scaled or region decode is for, and the planner reaches for one on its own.
Progressive JPEG cannot stream a region. Successive approximation needs the whole coefficient plane before any pixel is final, so a region request on a progressive file decodes the plane and then crops. probe reports progressive so a caller can tell in advance.
One module owns one linear memory. Load more than one for isolation between concurrent requests; sharing one is normally what you want, and the allocator returns every buffer at the end of a call.
Animation is first-frame only. GIF and WebP animations decode their first frame, and probe reports the frame count. A request with nothing to do passes the source through whole, so serving an animation unchanged keeps every frame; a request that has real work sets flattened on the result, because there is no animated encoder to write the rest back. Transforming all 57 frames of an 800x600 GIF to a 200 px thumbnail measures 335 ms, which is why the first frame is the default rather than a limitation waiting to be lifted.
A cascade is scale-dependent. No single search setting finds every face: a frontal face is found at a moderate reduction and lost at full resolution, and a side-facing one can be the reverse. detectFaces picks a default that suits frontal faces; the C entry point tiny_image_detect_faces_ex searches exactly what it is told.
-msimd128 currently buys nothing. No code path uses SIMD intrinsics, so the flag only enables an autovectorizer that -Oz disables. Measured at 0.97-1.02x on three operations.

Out of Scope

AVIF and HEIF decode and encode. An AV1 intra decoder is 8-10k lines against 8-10k for the rest of the library, decode runs 4-12x the JPEG path per pixel, and encode needs a rate-distortion search that costs seconds per image in wasm. The container parse ships so probe answers. Codecs register through a table, so a second module can carry AV1 for callers who ask.
JPEG XL. No browser ships it by default.
Animation editing. Composing or re-timing frames is a different product.
LUT-based ICC profiles. Rejected with a specific error rather than approximated.
AI-backed effects. No model, and a Worker is the wrong place for one.

API Reference

Generated documentation lives at tinyimg.gmitch215.dev: the
TypeScript surface under /typedoc, and the C headers under /doxygen.

Java on Cloudflare Workers

Gregory Mitchell — Mon, 31 Aug 2026 06:53:15 +0000

This post details bytebox, a dependency and runtime to get Java to run on Serverless Architecture via Cloudflare Workers. It uses TeaVM to compile Java into WebAssembly usable by the Cloudflare Workers runtime.

It comes in multiple forms: you can use it as a Gradle plugin to output a deployable worker or a WebAssembly module, and comes as a NPM module to assemble workers by hand. Java dependencies are available via Maven Central and the Gradle Plugin Portal.

An important note about Cloudflare Workers vs Java is that Cloudflare Workers is a single-threaded synchronous state, so all operations are blocking and concurrency is not possible from Java. java.util.concurrent and other threading operations are not included and will result in a compilation error from trying to use them. The GitHub repository lists the full scope of other platform limitations and out-of-scope items, including the use of Process and ProcessBuilder, dynamic class loading, and inbound TCP listening or UDP handlers with DatagramSocket or ServerSocket.

Currently supported are Java 21 and 25 LTS versions. Documentation for both the Java API and the TypeScript API is available at bytebox.gmitch215.dev.

Quick Start

Copied from the README page:

package com.example;

import dev.gmitch215.bytebox.*;

public class HelloWorker implements Worker {
    @Override
    public Response fetch(Request request, Env env, ExecutionCtx ctx) {
        return Bytebox.response("hello from Java");
    }
}

In your Gradle configuration:

plugins {
    java
    id("dev.gmitch215.bytebox") version "1.0.0"
}

repositories {
        mavenCentral()
}

dependencies { 
        implementation("dev.gmitch215:bytebox-core:1.0.0") 
}

// ...

bytebox {
    handlerClass = "com.example.HelloWorker" // to handler class

    wrangler {
        name = "hello-world" // name of cfw
        compatibilityDate = "2026-08-22" // compatibility date of cfw
    }
}

The Gradle plugin will compile your code to WebAssembly using TeaVM and output the necessary worker scaffholding to use wrangler dev or wrangler deploy:

./gradlew buildWorker # build wrangler.jsonc, webassembly module, entrypoint
./gradlew workerDeploy # run wrangler deploy to logged-in account

Bindings

All bindings available on Cloudflare Workers are supported in bytebox. The Gradle plugin allows you to easily add one or multiple bindings for your generated wrangler.jsonc, and provides default names if you so choose.

bytebox {
    bindings {
        kv()                             // KV
        kv("SESSIONS") { id = "abc123" } // an explicit name and a remote id
        d1()                             // DB
        r2()                             // BLOB
        durableObject("Counter")         // DO_COUNTER
    }
}

You can also declare them like so:

bytebox {
    bindings(KV, D1, D1, KV) // KV, DB, DB_2, KV_2
}

A Gradle task named bindingsReport is available to get detailed information about the bindings you have declared in your project.

JSON and Serialization

Many Cloudflare Workers handle and respond with JSON outputs. bytebox comes with buult-in utilities to parse and handle JSON.

To automatically serialize a class or a record, annotate it with @JsonType:

@JsonType
public record Order(String sku, int quantity, long total, List<String> tags) { // ... }

Bytebox.json serializes it to JSON:

Order order = request.json(Order.class);
return Bytebox.json(order, Order.class);

java.io is also supported normally, and requires no additional code.

byte[] wire = Serial.encode(order);
Order back = Serial.decode(wire, Order.class);

Dependencies & Runtime

Java Standard Libraries

bytebox and TeaVM provide polyfills and runtime capabilities for you to use the majority of the Java Standard Library without any code modification. The Gradle plugin will automatically rewrite any class files or dependencies routed to a systems class that requires a polyfill, so no code modification is required.

ZonedDateTime local = Instant.now().atZone(ZoneId.of("America/New_York"));
HttpResponse<String> answer = HttpClient.newHttpClient()
    .send(HttpRequest.newBuilder(URI.create("https://example.com")).build(), ofString());

Libraries like java.time, java.net, java.io, java.util.regex, and many others can be written like you would normally.

package com.example;

import dev.gmitch215.bytebox.Bytebox;
import dev.gmitch215.bytebox.Env;
import dev.gmitch215.bytebox.ExecutionCtx;
import dev.gmitch215.bytebox.Request;
import dev.gmitch215.bytebox.Response;
import dev.gmitch215.bytebox.Worker;
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.time.Instant;
import java.time.LocalDate;
import java.time.ZoneId;
import java.time.ZonedDateTime;
import java.time.format.DateTimeFormatter;
import java.time.temporal.ChronoUnit;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

/**
 * Ordinary Java, on a platform that has none of it.
 *
 * <p>Nothing here is a bytebox API. It is {@code java.time}, {@code java.net.http},
 * {@code java.util.regex} and {@code String.format}, written the way they are written anywhere, and
 * the compiler points each reference at an implementation that works on this runtime. That is what
 * makes an unmodified library compile: the library does not know it is being retargeted.
 *
 * <p>What each one costs, and where each one differs from a JVM, is in the technical report. The two
 * differences worth knowing at the call site are here as comments.
 */
public class StandardLibraryWorker implements Worker {

    private static final Pattern SINCE = Pattern.compile("since=(?<date>\\d{4}-\\d{2}-\\d{2})");

    private static final HttpClient CLIENT = HttpClient.newBuilder()
        .connectTimeout(Duration.ofSeconds(5))
        .build();

    @Override
    public Response fetch(Request request, Env env, ExecutionCtx ctx) {
        LocalDate since = LocalDate.of(2026, 1, 1);
        Matcher asked = SINCE.matcher(request.getUrl());
        if (asked.find()) since = LocalDate.parse(asked.group("date"));

        // the clock is pinned between I/O, so this is the time the invocation began and does not move
        Instant now = Instant.now();
        ZonedDateTime local = now.atZone(ZoneId.of("America/New_York"));
        long days = ChronoUnit.DAYS.between(since, local.toLocalDate());

        StringBuilder body = new StringBuilder();
        body.append(local.format(DateTimeFormatter.ISO_OFFSET_DATE_TIME)).append('\n');
        // %,d groups every three digits here, which is right for the locales that group in threes
        body.append(String.format("%,d days since %s%n", days, since));
        body.append(String.format("%-12s %8.2f%%%n", "elapsed", (days * 100.0) / 365));
        body.append(upstream()).append('\n');

        return Bytebox.response(body.toString());
    }

    /** A request through the modern client, which is {@code fetch} underneath and suspends the fiber. */
    private String upstream() {
        try {
            HttpResponse<String> answer = CLIENT.send(
                HttpRequest.newBuilder(URI.create("https://example.com/"))
                    .header("Accept", "text/html")
                    .timeout(Duration.ofSeconds(3))
                    .build(),
                HttpResponse.BodyHandlers.ofString()
            );
            return String.format(
                "upstream %d, %,d bytes",
                answer.statusCode(),
                answer.body().length()
            );
        } catch (IOException | InterruptedException failed) {
            return "upstream unreachable: " + failed.getMessage();
        }
    }
}

npm Dependencies

The bytebox Gradle plugin supports adding NPM dependencies to your worker, and comes with static analysis to generate supported types based on the npm module to use in your Java code.

bytebox {
    npm("nanoid", "^5.0.9")
    npmBindings("nanoid")
}

npm installs the dependency, and npmBindings tells the plugin to read the *.d.ts declarations in the npm module to generate Java source files that you can use to work with the package.

You can also use the @JSBody annotation that TeaVM provides with the native keyword to wire it directly:

@JSBody(
    params = "size",
    imports = @JSBodyImport(alias = "nanoid", fromModule = "nanoid"),
    script = "return nanoid.nanoid(size);"
)
private static native String id(int size);

Third-Party Java Dependencies

Dependencies can be declared as normal and they will be compiled in with the worker.

dependencies {
        implementation("com.example:foo:1.0.0")
}

Cloudflare Workers' free plan has a hard limit of 3 MiB after gzip on the bundle, with paid increasing to 10 MiB after gzip, so installing heavy Java dependencies should be done with care. TeaVM only includes parts of the Java runtime that it detects is being used, and does not include the full runtime on compilation (unless everything is being used). The estimation for each runtime feature's cost is provided below.

Feature	Added, gzipped
streams, collections, reflection	3.0 to 3.8 KB each
threads	6.8 KB
`java.net.Socket`	9.8 KB
`BigDecimal`	12.7 KB
`java.util.regex`	13.3 KB
`java.net.URL` and `HttpURLConnection`	13.3 KB
`java.time` with zones	23.8 KB
`String.format`	33.0 KB
`java.net.http`	54.1 KB

Cloudflare Runtime Libraries

Cloudflare Workers provides runtime libraries like cloudflare:sockets, cloudflare:mail, and many other built-ins available to you. bytebox provides Java API around these out of the box so you can use them how you please.

Examples

Borrowed from the GitHub repository's snippets.

Cron Job

All triggers are supported in bytebox, and cron is not an exception.

package com.example;

import dev.gmitch215.bytebox.Bytebox;
import dev.gmitch215.bytebox.Cron;
import dev.gmitch215.bytebox.Env;
import dev.gmitch215.bytebox.ExecutionCtx;
import dev.gmitch215.bytebox.Scheduled;
import dev.gmitch215.bytebox.builtin.Clock;

/**
 * A Worker with no HTTP handler at all.
 *
 * <p>Implementing only {@code Scheduled} means the generated Worker exports only {@code scheduled},
 * and the generated configuration carries only the trigger. Nothing is exported for a trigger the
 * handler does not implement.
 *
 * <p>An account gets 5 Cron Triggers on the free plan and 250 on paid, counted across every Worker
 * rather than per Worker. A scheduled invocation gets 15 minutes rather than a request's allowance,
 * and a throw is logged without a retry.
 */
public class NightlyWorker implements Scheduled {

    @Override
    public void scheduled(Cron cron, Env env, ExecutionCtx ctx) {
        Bytebox.log("fired for " + cron.expression() + ", due at " + Clock.iso(cron.scheduledAt()));
        env.kv().put("last-run", Clock.isoNow());
    }
}

Durable Objects

Durable Objects are supported out-of-the-box with bytebox. They can either be used directly or be implemented over as a class.

package com.example;

import dev.gmitch215.bytebox.Bytebox;
import dev.gmitch215.bytebox.Env;
import dev.gmitch215.bytebox.ExecutionCtx;
import dev.gmitch215.bytebox.Request;
import dev.gmitch215.bytebox.Response;
import dev.gmitch215.bytebox.Worker;
import dev.gmitch215.bytebox.binding.DurableObjectNamespace;
import dev.gmitch215.bytebox.js.TSObject;

/**
 * Routes to a Durable Object, which is where state that has to be exact belongs.
 *
 * <p>One instance per id, in one place, so two requests for the same id reach the same instance and
 * see each other's writes. That is the difference from the kv-counter sample, where two regions can
 * both read the same value and both write the next one.
 *
 * <p>The Durable Object class itself is JavaScript: it extends Cloudflare's own base class, which is
 * a JavaScript class the runtime instantiates. What Java owns is the routing and the calls.
 */
public class CounterWorker implements Worker {

    @Override
    public Response fetch(Request request, Env env, ExecutionCtx ctx) {
        DurableObjectNamespace counters = env.durableObject("DO_COUNTER");

        // the id is derived from the path, so every path gets its own instance
        var counter = counters.byName(request.path());
        TSObject count = counter.rpc("increment");

        return Bytebox.response(request.path() + " is at " + count.asInt() + "\n");
    }
}

Mail Routing

Cloudflare Workers can receive inbound mail, allowing code to handle and reroute any incoming mail it receives. The InboundMail class provided as apart of the implementation surface will automatically handle it based on the method you call, whether it is mail.forward, mail.reject, or anything else you choose to do with it.

package com.example;

import dev.gmitch215.bytebox.Bytebox;
import dev.gmitch215.bytebox.Env;
import dev.gmitch215.bytebox.ExecutionCtx;
import dev.gmitch215.bytebox.InboundMail;
import dev.gmitch215.bytebox.Mail;

/**
 * An inbound email router.
 *
 * <p>Cloudflare drops a message a handler returns without acting on, so {@code InboundMail} records
 * what was done and raises if nothing was. That makes the silent drop impossible to reach by
 * accident, and {@code drop()} is how to say the silence was meant.
 *
 * <p>Inbound messages are capped at 25 MiB. A reply needs the original to have passed DMARC, has to
 * come from the receiving domain, and is allowed once per message.
 */
public class MailRouter implements Mail {

    @Override
    public void email(InboundMail mail, Env env, ExecutionCtx ctx) {
        if (mail.rawSize() > 1_000_000) {
            mail.reject("messages over 1 MB are not accepted");
            return;
        }

        String sender = mail.from();
        if (env.kv().get("blocked:" + sender) != null) {
            mail.reject("this address is not accepted");
            return;
        }

        // acting and then carrying on is the point: the disposition is recorded on the message
        Bytebox.log("routing " + mail.rawSize() + " bytes from " + sender);
        env.kv().put("last-sender", sender);
        mail.forward("inbox@example.com");
    }
}

Queue Consumer

Cloudflare Workers also supports using Queues as a trigger to handle multiple messages sent to the worker to be processed individually.

package com.example;

import dev.gmitch215.bytebox.Bytebox;
import dev.gmitch215.bytebox.Consumer;
import dev.gmitch215.bytebox.Env;
import dev.gmitch215.bytebox.ExecutionCtx;
import dev.gmitch215.bytebox.Message;
import dev.gmitch215.bytebox.MessageBatch;
import dev.gmitch215.bytebox.js.TSObject;

/**
 * A Queue consumer that acknowledges each message separately.
 *
 * <p>An uncaught exception retries the whole batch, which is rarely what a partial failure wants.
 * Acknowledging and retrying per message is how one bad message stops holding up the rest.
 *
 * <p>A body is any structured-clone value, so it arrives as a {@code TSObject}. A body with a known
 * shape can be read with a codec instead; see the {@code @JSONType} annotation.
 */
public class OrderConsumer implements Consumer<TSObject> {

    @Override
    public void queue(MessageBatch<TSObject> batch, Env env, ExecutionCtx ctx) {
        var insert = env.d1().prepare("insert into orders (id, sku) values (?, ?)");

        for (Message<TSObject> message : batch.messages()) {
            try {
                TSObject body = message.body();
                insert.bind(message.id(), body.get("sku").asString()).run();
                message.ack();
            } catch (RuntimeException failure) {
                Bytebox.log("order " + message.id() + " failed: " + failure.getMessage());
                // a fourth attempt is unlikely to go differently, so give up rather than loop
                if (message.attempts() >= 3) message.ack();
                else message.retry(30);
            }
        }
    }
}

HTTP API Router

bytebox comes with a Router class that makes it easy to use Java to make HTTP APIs. You can use them to build a tree of routes, similar to tools like Hono.

import dev.gmitch215.bytebox.http.Router;

public class Api implements Worker {

    private final Router routes = new Router()
        .filter(Api::requireToken)
        .get("/things", (request, env, ctx) -> Bytebox.json(env.d1().query("select * from things")))
        .get("/things/:id", (request, env, ctx) -> one(env, request.param("id")))
        .post("/things", Api::create);

    @Override
    public Response fetch(Request request, Env env, ExecutionCtx ctx) {
        return routes.handle(request, env, ctx);
    }

        // implement create(), requireToken(), and others below
}

TCP Worker

The cloudflare:sockets module allows workers to send outbound TCP bytes to a specific hostname and port. No library is provided and only a raw connectTls function is provided, so libraries like edgeport can be used to wrap around SSH, SMTP, FTP, LDAP, and other TCP protocols you may need to use. Note that Cloudflare currently lists that it does not allow outbound TCP connections to its IP addresses or on port 22 directly.

package com.example;

import dev.gmitch215.bytebox.Bytebox;
import dev.gmitch215.bytebox.Env;
import dev.gmitch215.bytebox.ExecutionCtx;
import dev.gmitch215.bytebox.Request;
import dev.gmitch215.bytebox.Response;
import dev.gmitch215.bytebox.Worker;
import dev.gmitch215.bytebox.socket.Socket;
import dev.gmitch215.bytebox.socket.Sockets;

/**
 * A raw TCP client over {@code cloudflare:sockets}.
 *
 * <p>What this cannot reach decides whether it is the right tool. Cloudflare refuses a connection to
 * its own IP ranges, to localhost and to private addresses, and blocks port 25. So a Worker cannot
 * SMTP to Cloudflare Email Sending even with valid credentials; the email binding is the way out.
 *
 * <p>Every plan allows six simultaneous outgoing connections, so the socket is closed rather than
 * left to the runtime. Try-with-resources is why {@code Socket} is {@code AutoCloseable}.
 */
public class TcpWorker implements Worker {

    @Override
    public Response fetch(Request request, Env env, ExecutionCtx ctx) {
        String host = request.query("host", "example.com");

        try (Socket socket = Sockets.connectTLS(host, 443)) {
            socket.write("HEAD / HTTP/1.0\r\nHost: " + host + "\r\nConnection: close\r\n\r\n");
            String status = socket.readUntil("\r\n");
            return Bytebox.response(host + " answered " + status + "\n");
        } catch (RuntimeException refused) {
            // the refusal reads "proxy request failed, cannot connect to the specified address"
            return Bytebox.response("could not reach " + host + ": " + refused.getMessage(), 502);
        }
    }
}

Intermediate Example

package example;

import dev.gmitch215.bytebox.Env;
import dev.gmitch215.bytebox.ExecutionCtx;
import dev.gmitch215.bytebox.Request;
import dev.gmitch215.bytebox.Response;
import dev.gmitch215.bytebox.Worker;
import dev.gmitch215.bytebox.Bytebox;
import dev.gmitch215.bytebox.http.Filter;
import dev.gmitch215.bytebox.http.Route;
import dev.gmitch215.bytebox.http.Router;

import java.util.Map;
import java.util.Optional;

/**
 * A moderately realistic ByteBox Worker demonstrating:
 *
 * <ul>
 *     <li>HTTP routing</li>
 *     <li>Path parameters</li>
 *     <li>Query parameters</li>
 *     <li>Route-specific middleware</li>
 *     <li>Global middleware</li>
 *     <li>Authentication</li>
 *     <li>Request validation</li>
 *     <li>JSON responses</li>
 *     <li>404 handling</li>
 *     <li>Basic error handling</li>
 * </ul>
 *
 * <p>The handlers deliberately use ordinary Java control flow. ByteBox's
 * Worker runtime handles suspension when a handler performs supported I/O.</p>
 */
public final class ApiWorker implements Worker {

    private final Router router;

    public ApiWorker() {
        this.router = buildRouter();
    }

    /**
     * Worker entry point.
     *
     * <p>All requests are handed to the Router. The router is responsible
     * for matching the HTTP method/path and executing middleware before
     * invoking the selected handler.</p>
     */
    @Override
    public Response fetch(
            Request request,
            Env env,
            ExecutionCtx ctx
    ) {
        try {
            return router.route(request, env, ctx);
        } catch (Exception e) {
            // In production, log the exception rather than returning its
            // details to the client.
            Bytebox.log("Unhandled request error: " + e);

            return Bytebox.json(
                    """
                    {
                      "error": "internal_server_error"
                    }
                    """,
                    500
            );
        }
    }

    /**
     * Constructs the application router.
     *
     * <p>Middleware registered with {@code use()} runs for matching requests
     * before the route handler. Route-specific filters can additionally be
     * supplied when registering an individual route.</p>
     */
    private Router buildRouter() {
        Router router = Router.create();

        /*
         * ------------------------------------------------------------------
         * Global middleware
         * ------------------------------------------------------------------
         */

        // Add a request ID to every request and expose it through the
        // response headers. In a larger application this could instead
        // attach information to a request context abstraction.
        router.use(requestIdMiddleware());

        // Reject unsupported HTTP methods before route dispatch.
        router.use(methodGuardMiddleware());

        /*
         * ------------------------------------------------------------------
         * Public routes
         * ------------------------------------------------------------------
         */

        router.get(
                "/",
                (request, path, env, ctx) ->
                        Bytebox.json(
                                """
                                {
                                  "name": "example-api",
                                  "status": "ok"
                                }
                                """
                        )
        );

        router.get(
                "/health",
                this::health
        );

        /*
         * Query parameters can be read from the request URL.
         *
         * Example:
         *
         *     GET /users?limit=20
         *
         * The exact URL/query representation comes from ByteBox's Request
         * abstraction, while the rest of the handler remains ordinary Java.
         */
        router.get(
                "/users",
                this::listUsers
        );

        /*
         * ------------------------------------------------------------------
         * Authenticated routes
         * ------------------------------------------------------------------
         *
         * Authentication is applied only to this group of routes rather
         * than globally, so /health and / can remain public.
         */

        router.get(
                "/me",
                authenticated(),
                this::currentUser
        );

        router.get(
                "/users/:id",
                authenticated(),
                this::getUser
        );

        router.post(
                "/users",
                authenticated(),
                this::createUser
        );

        /*
         * ------------------------------------------------------------------
         * Admin routes
         * ------------------------------------------------------------------
         *
         * Multiple filters can be composed. Authentication runs first;
         * authorization runs only after authentication succeeds.
         */

        router.delete(
                "/users/:id",
                authenticated(),
                requireRole("admin"),
                this::deleteUser
        );

        /*
         * ------------------------------------------------------------------
         * Wildcard example
         * ------------------------------------------------------------------
         *
         * A wildcard route can be useful for proxy-like or asset-like
         * endpoints.
         */
        router.get(
                "/debug/*",
                authenticated(),
                requireRole("admin"),
                this::debug
        );

        /*
         * ------------------------------------------------------------------
         * 404
         * ------------------------------------------------------------------
         *
         * Router invokes this handler when no registered route matches.
         */
        router.notFound(
                (request, path, env, ctx) ->
                        Bytebox.json(
                                """
                                {
                                  "error": "not_found"
                                }
                                """,
                                404
                        )
        );

        return router;
    }

    /**
     * Simple request-ID middleware.
     *
     * <p>Middleware receives a {@link java.util.function.Supplier} for the
     * next handler. Calling {@code next.get()} continues the request.</p>
     */
    private Filter requestIdMiddleware() {
        return (request, path, env, ctx, next) -> {
            String requestId = Bytebox.uuid();

            Response response = next.get();

            /*
             * The Response API exposes its headers, allowing middleware
             * to add information to an otherwise completed response.
             */
            response.getHeaders().set("X-Request-ID", requestId);

            return response;
        };
    }

    /**
     * Example global middleware that rejects methods which the application
     * does not intend to support.
     *
     * <p>Route matching still determines whether a particular endpoint
     * exists; this filter merely demonstrates application-level policy.</p>
     */
    private Filter methodGuardMiddleware() {
        return (request, path, env, ctx, next) -> {
            String method = request.getMethod();

            if (method == null) {
                return Bytebox.json(
                        """
                        {
                          "error": "invalid_request"
                        }
                        """,
                        400
                );
            }

            return switch (method) {
                case "GET", "POST", "PUT", "PATCH", "DELETE" ->
                        next.get();

                default ->
                        Bytebox.json(
                                """
                                {
                                  "error": "method_not_allowed"
                                }
                                """,
                                405
                        );
            };
        };
    }

    /**
     * Authentication middleware.
     *
     * <p>This example intentionally keeps authentication simple. A real
     * implementation could validate a JWT, call an identity service, or
     * inspect a signed session cookie.</p>
     */
    private Filter authenticated() {
        return (request, path, env, ctx, next) -> {
            String authorization = request.getHeaders().get("Authorization");

            if (authorization == null ||
                    !authorization.startsWith("Bearer ")) {

                return Bytebox.json(
                        """
                        {
                          "error": "unauthorized"
                        }
                        """,
                        401
                );
            }

            String token = authorization.substring("Bearer ".length());

            if (!isValidToken(token)) {
                return Bytebox.json(
                        """
                        {
                          "error": "invalid_token"
                        }
                        """,
                        401
                );
            }

            /*
             * ByteBox does not require middleware to be a particular
             * authentication framework. Application state can be carried
             * through whatever application-level context abstraction the
             * application uses.
             *
             * This example simply demonstrates successful middleware
             * continuation.
             */
            return next.get();
        };
    }

    /**
     * Authorization middleware.
     *
     * <p>In a production application, the user's authenticated identity
     * would normally come from a request context established by the
     * authentication layer.</p>
     */
    private Filter requireRole(String requiredRole) {
        return (request, path, env, ctx, next) -> {
            /*
             * Demo-only authorization decision.
             *
             * Replace this with the application's actual identity/context
             * lookup.
             */
            String role = request.getHeaders().get("X-Debug-Role");

            if (!requiredRole.equals(role)) {
                return Bytebox.json(
                        """
                        {
                          "error": "forbidden"
                        }
                        """,
                        403
                );
            }

            return next.get();
        };
    }

    /**
     * GET /health
     */
    private Response health(
            Request request,
            Map<String, String> path,
            Env env,
            ExecutionCtx ctx
    ) {
        return Bytebox.json(
                """
                {
                  "status": "healthy"
                }
                """
        );
    }

    /**
     * GET /users
     *
     * <p>Demonstrates reading query parameters and producing a JSON
     * response. The application could replace the in-memory list with
     * a D1 query without changing the routing structure.</p>
     */
    private Response listUsers(
            Request request,
            Map<String, String> path,
            Env env,
            ExecutionCtx ctx
    ) {
        String url = request.getUrl();

        int limit = extractLimit(url);

        if (limit < 1 || limit > 100) {
            return Bytebox.json(
                    """
                    {
                      "error": "limit_must_be_between_1_and_100"
                    }
                    """,
                    400
            );
        }

        /*
         * Normally:
         *
         *     env.d1()
         *         .prepare("SELECT ... LIMIT ?")
         *         .bind(limit)
         *         .all();
         *
         * would be used here.
         */
        String json = """
                {
                  "users": [
                    {
                      "id": 1,
                      "name": "Ada"
                    },
                    {
                      "id": 2,
                      "name": "Grace"
                    }
                  ],
                  "limit": %d
                }
                """.formatted(limit);

        return Bytebox.json(json);
    }

    /**
     * GET /me
     */
    private Response currentUser(
            Request request,
            Map<String, String> path,
            Env env,
            ExecutionCtx ctx
    ) {
        return Bytebox.json(
                """
                {
                  "id": 42,
                  "name": "Example User",
                  "role": "admin"
                }
                """
        );
    }

    /**
     * GET /users/:id
     *
     * <p>The {@code path} map contains the named route parameter:
     *
     * <pre>
     *     /users/:id
     *           ^
     *           └── path.get("id")
     * </pre>
     */
    private Response getUser(
            Request request,
            Map<String, String> path,
            Env env,
            ExecutionCtx ctx
    ) {
        String id = path.get("id");

        if (id == null || id.isBlank()) {
            return Bytebox.json(
                    """
                    {
                      "error": "missing_user_id"
                    }
                    """,
                    400
            );
        }

        if (!id.matches("\\d+")) {
            return Bytebox.json(
                    """
                    {
                      "error": "user_id_must_be_numeric"
                    }
                    """,
                    400
            );
        }

        /*
         * A real D1-backed implementation could do:
         *
         *     var result = env.d1()
         *         .prepare("SELECT id, name FROM users WHERE id = ?")
         *         .bind(Long.parseLong(id))
         *         .first();
         */

        return Bytebox.json(
                """
                {
                  "id": %s,
                  "name": "Example User"
                }
                """.formatted(id)
        );
    }

    /**
     * POST /users
     *
     * <p>Demonstrates reading a request body as JSON. The actual application
     * would normally deserialize into a generated ByteBox JSON codec type.</p>
     */
    private Response createUser(
            Request request,
            Map<String, String> path,
            Env env,
            ExecutionCtx ctx
    ) {
        String body = request.text();

        if (body == null || body.isBlank()) {
            return Bytebox.json(
                    """
                    {
                      "error": "request_body_required"
                    }
                    """,
                    400
            );
        }

        /*
         * Example body:
         *
         * {
         *   "name": "Linus"
         * }
         *
         * For a real application, prefer a @JSONType-generated codec instead
         * of manually parsing strings.
         */

        if (!body.contains("\"name\"")) {
            return Bytebox.json(
                    """
                    {
                      "error": "name_required"
                    }
                    """,
                    422
            );
        }

        /*
         * A real implementation could insert into D1 here and return the
         * newly-created resource.
         */
        Response response = Bytebox.json(
                """
                {
                  "id": 100,
                  "name": "New User"
                }
                """,
                201
        );

        response.getHeaders().set(
                "Location",
                "/users/100"
        );

        return response;
    }

    /**
     * DELETE /users/:id
     *
     * <p>Authentication and admin authorization have already been handled
     * by route-specific middleware before this method executes.</p>
     */
    private Response deleteUser(
            Request request,
            Map<String, String> path,
            Env env,
            ExecutionCtx ctx
    ) {
        String id = path.get("id");

        if (id == null || !id.matches("\\d+")) {
            return Bytebox.json(
                    """
                    {
                      "error": "invalid_user_id"
                    }
                    """,
                    400
            );
        }

        /*
         * Real implementation:
         *
         *     env.d1()
         *         .prepare("DELETE FROM users WHERE id = ?")
         *         .bind(Long.parseLong(id))
         *         .run();
         */

        return Bytebox.status(204);
    }

    /**
     * GET /debug/*
     *
     * <p>Demonstrates a wildcard route. The router places the matched
     * path information into the route parameter map.</p>
     */
    private Response debug(
            Request request,
            Map<String, String> path,
            Env env,
            ExecutionCtx ctx
    ) {
        String wildcard = path.get("*");

        return Bytebox.json(
                """
                {
                  "debug": true,
                  "path": %s
                }
                """.formatted(
                        jsonString(wildcard == null ? "" : wildcard)
                )
        );
    }

    /**
     * Demo token validator.
     *
     * <p>Replace this with actual signature verification / identity lookup.
     * No secret is embedded in application code.</p>
     */
    private boolean isValidToken(String token) {
        return !token.isBlank() && token.length() >= 16;
    }

    /**
     * Minimal query-string extraction used only to keep the example focused
     * on Router rather than URL parsing.
     *
     * <p>For production code, use ByteBox's URL/request facilities rather
     * than relying on this deliberately small helper.</p>
     */
    private int extractLimit(String url) {
        if (url == null) {
            return 20;
        }

        int queryStart = url.indexOf('?');

        if (queryStart < 0) {
            return 20;
        }

        String query = url.substring(queryStart + 1);

        for (String parameter : query.split("&")) {
            String[] parts = parameter.split("=", 2);

            if (parts.length == 2 && parts[0].equals("limit")) {
                try {
                    return Integer.parseInt(parts[1]);
                } catch (NumberFormatException ignored) {
                    return -1;
                }
            }
        }

        return 20;
    }

    /**
     * Escapes a string sufficiently for this small JSON demonstration.
     *
     * <p>Use ByteBox's generated JSON codecs for real application models.</p>
     */
    private String jsonString(String value) {
        if (value == null) {
            return "null";
        }

        return "\"" + value
                .replace("\\", "\\\\")
                .replace("\"", "\\\"")
                .replace("\n", "\\n")
                .replace("\r", "\\r")
                .replace("\t", "\\t")
                + "\"";
    }
}

Conclusion

This was a short demonstration about how to use bytebox to get Java to run on Cloudflare Workers. You can use it to interop between JavaScript and Java on serverless state to maximize the capabilities of your applications.

What I Learned from 700 Hours of Kotlin

Gregory Mitchell — Thu, 20 Aug 2026 19:19:33 +0000

Ported from my blog on August 20, 2026.

While I was working on Kray, I crossed 700 hours of work on Kotlin. This post will be about my thoughts about the language.

For reference, I started with Kotlin all the way back in 2020 to 2021. Which means I started during prime pre-GPT days before I had Copilot fix all of my bugs for me. It was really fun learning about the language and all it had to offer.

My first project was PlasmaEnchants, a Minecraft plugin with custom enchantments. It was a good starter project that helped me grasp and eventually come to love the language. Now, what will be five years later, I've absorbed myself into the Kotlin community on pretty much every major front. I did some Android and Web development with the Combinatory Game, some Kotlin/JVM single repository projects like with benchmarks, some Kotlin/Native stuff with KNCR and Kray, some Kotlin/JS stuff with @earth-app/ocean and @earth-app/shovel, and some Multiplatform stuff with TabroomAPI. Maybe I'll finish kasciffy at some point as well.
The Good

Kotlin is a good programming language. It's comfortable, lightweight, and easily extendable. Good languages should emphasize the developer experience as much as possible, in my own personal opinion. It's why I've never really clicked with C++, and more so stick to C. Same for why I tried to get into Go but couldn't really adapt to the new syntax. I started out with the C family languages like Java and TypeScript, so Kotlin was a nice touch for me.

I've written about this before, but Kotlin Multiplatform is extremely powerful. I think JetBrains is slowly starting to realize the potential of a language that can interop with both a virtual machine, native code, and client code. It's something I've tried to explore and extend with, which is one of the primary flaws that I'll get to later.

The other major good point that I think Kotlin has is its documentation. While there are some improvements to be made (again, I will mention later), the documentation overall is good. I know there is this sentiment for the developers of a language to document things themselves, but I think the fact that the Kotlin Foundation is primarily sponsored by a company that makes over $722 million dollars a year is a reason for them to at least try and keep the documentation correct.
The Bad

"Bad" sounds bad. There aren't really bad things about Kotlin. A lot of languages have bugs in them, and Kotlin is no different. I just don't think a major bug that I reported six months ago should still be in development, especially by said multi-million dollar company. But I can't really blame them.

One of the pitfalls of Kotlin is that it is still a new language. It wants to do a lot of stuff. To kind of emphasize this point, let's list some of the features of Kotlin:

Work with C and C++
Work with JavaScript
Work with Java
Work with Android platforms
Work as a server backend
Work with AI models in embedding and training

This means that you could, with enough effort and hacks, write:

The entire Kotlin toolchain in Kotlin
A C compiler in Kotlin
An operating system in Kotlin
The source control for that operating system
A recreation of Minecraft on the operating system
A browser for that operating system
A webpage displayed on that browser
A server powering that browser
The firewall security for that server
A dashboard to control the firewall security
An AI to summarize and present the information from the dashboard

all in the same language.

The more features you add, the more bugs you will get. That's just how software is. Just like how giving out more food can get more people sick. This also goes back to the documentation point I've made earlier; it's pretty big and sometimes misses a lot of updates. I would say the page I look at the post is the documentation for the C interop file, since that has been where a majority of my projects lay in, post-Minecraft dev. The page is informative, for the most part, but as of writing this, it's missing a lot of advanced setup details that I had to figure out myself. For example, it turns out that the filters like headers.osx or linkerOpts.macos_x64 point to an enum of either the OS family or target type. Would have been really helpful when I was trying to figure out KNCR.

Another minor gripe I had was the fact that JetBrains seemed to be really stubborn about providing support on anything that wasn't IntelliJ. A couple of unofficial plugins tried to add support on VSCode or Eclipse, but they never were on the scale that IntelliJ provided. They caved in May to create a VSCode Plugin, but like most things in Kotlin, it's new and likely will need a few more years to mature.
This is also linked to a previous language I've worked with on The Earth App, that there is a consequence to prioritizing an enterprise feel over an open-source feel. Rust is one of the most loved by developers because it's open source first. That may be an oversimplification, but it's still a major reason. TypeScript is also one of the most loved, and it's backed by Microsoft. It's just two different kinds of programming languages. The multi-million dollar funding could be incorporated with more developer say to make the overall DX better. Kotlin being backed by JetBrains isn't a bad thing, nor is Java being backed by Oracle. They both work, and a mix can be even better.

These highlight the only problems I have with Kotlin. I've given up on a lot of projects, both side and main, because I had to wait for forever to get an issue fixed, or fiddle through a bunch of enterprise stuff. No hate to any individual or entity. Just the reality of shiny, new languages, I guess.
The Hope

I think Kotlin will go far. I also think JetBrains could spend more time putting effort into the Kotlin open source community instead of whatever AI stuff they're doing or trying to compete with our goat VSCode. Sounds like common criticisms of a corporation, I guess.

I mostly say that because the subset I spend the majority of my time in, Kotlin/Native, hasn't really seen any kind of significant improvement. There's no Windows ARM target, you can't use the toolchain on a Linux ARM machine, and the whole tool kind of feels strung together so that your average junior dev can just do the same thing every time. Looking through the Compose Multiplatform code can kind of show this, though they did put a lot of investment in Android and JVM interoperability. Because JetBrains controls a significant majority of what happens to Kotlin, I hope they clean up those loose wires in the next few years. Especially as Kotlin begins to weave itself into more and more infrastructure.

I'm excited for the future of the language. I love Kotlin to death, and I hope it continues to grow as much as it does. Add some minor tweaks and bug fixes and maybe we'll see it beat even Python one day.

[Boost]

Gregory Mitchell — Wed, 21 May 2025 14:55:14 +0000

Gregory Mitchell

May 14 '25

Kotlin's Performance and What it Means

#kotlin #programming #coding #performance

6 min read

Kotlin's Performance and What it Means

Gregory Mitchell — Wed, 14 May 2025 15:02:17 +0000

Kotlin is a modern programming language that has gained popularity for its concise syntax and interoperability with Java. As I've been exploring Kotlin, it's come to become my favorite programming language. I built the benchmarks application in Kotlin, and included Kotlin as one of the languages it compares against. In this post, I want to share my thoughts on Kotlin's performance and how it compares to other languages.

Performance Overview

Kotlin JVM ranks last. And it's not close.

At first, I thought this was a fault on my part. Maybe I was measuring the wrong thing, or maybe I was using the wrong libraries. But after some investigation, I found that Kotlin's performance is consistently lower than the rest of the languages in the benchmarks. I even decided to turn on compiler optimizations for this language at one point, and it still didn't help.

Let's take a look at how the app actually works. It works by running the same program simultaneously 25 times and taking the average of the results. This means that if one of the programs is slow, it will affect the overall performance. However, it also includes the minimum time it took to run the program, which is a good indicator of how fast the program can be. This means that if one of the programs is slow, it will affect the overall performance.

Bubble Sort Example

Here's an example using the Bubble Sort benchmark that I created:

I immediately notice some very high spikes. This must mean that it's dragging down the average time, right?

Nope.

Kotlin Native performs at the benchmark I would expect it to run, but it's minimum time is still leagues behind the other languages. This means that even though it can run at a decent speed, it still has a lot of room for improvement. However, let's remind ourselves that this was measured in microseconds, with a fundamental difference of only just a millisecond or two. This is a very small difference, and it can be attributed to the fact that Kotlin is a newer language and is still being optimized. However, I would expect it to be at least on par with the other languages in the benchmarks.

Why is This?

Let's take a look at some decompiled Kotlin code. This is a decompiled example of the TabroomAPI library that I created.

/* Decompiler 33ms, total 130ms, lines 156 */
package dev.gmitch215.tabroom.api;

import kotlin.Metadata;
import kotlin.jvm.internal.Intrinsics;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;

@Metadata(
   mv = {2, 1, 0},
   k = 1,
   xi = 48,
   d1 = {"\u0000\"\n\u0002\u0018\u0002\n\u0002\u0010\u0000\n\u0000\n\u0002\u0010\u000e\n\u0002\b\u0004\n\u0002\u0010\u000b\n\u0002\b\u0012\n\u0002\u0010\b\n\u0002\b\u0002\b\u0087\b\u0018\u00002\u00020\u0001B/\u0012\u0006\u0010\u0002\u001a\u00020\u0003\u0012\u0006\u0010\u0004\u001a\u00020\u0003\u0012\u0006\u0010\u0005\u001a\u00020\u0003\u0012\u0006\u0010\u0006\u001a\u00020\u0003\u0012\u0006\u0010\u0007\u001a\u00020\b¢\u0006\u0004\b\t\u0010\nJ\t\u0010\u0012\u001a\u00020\u0003HÆ\u0003J\t\u0010\u0013\u001a\u00020\u0003HÆ\u0003J\t\u0010\u0014\u001a\u00020\u0003HÆ\u0003J\t\u0010\u0015\u001a\u00020\u0003HÆ\u0003J\t\u0010\u0016\u001a\u00020\bHÆ\u0003J;\u0010\u0017\u001a\u00020\u00002\b\b\u0002\u0010\u0002\u001a\u00020\u00032\b\b\u0002\u0010\u0004\u001a\u00020\u00032\b\b\u0002\u0010\u0005\u001a\u00020\u00032\b\b\u0002\u0010\u0006\u001a\u00020\u00032\b\b\u0002\u0010\u0007\u001a\u00020\bHÆ\u0001J\u0013\u0010\u0018\u001a\u00020\b2\b\u0010\u0019\u001a\u0004\u0018\u00010\u0001HÖ\u0003J\t\u0010\u001a\u001a\u00020\u001bHÖ\u0001J\t\u0010\u001c\u001a\u00020\u0003HÖ\u0001R\u0011\u0010\u0002\u001a\u00020\u0003¢\u0006\b\n\u0000\u001a\u0004\b\u000b\u0010\fR\u0011\u0010\u0004\u001a\u00020\u0003¢\u0006\b\n\u0000\u001a\u0004\b\r\u0010\fR\u0011\u0010\u0005\u001a\u00020\u0003¢\u0006\b\n\u0000\u001a\u0004\b\u000e\u0010\fR\u0011\u0010\u0006\u001a\u00020\u0003¢\u0006\b\n\u0000\u001a\u0004\b\u000f\u0010\fR\u0011\u0010\u0007\u001a\u00020\b¢\u0006\b\n\u0000\u001a\u0004\b\u0010\u0010\u0011¨\u0006\u001d"},
   d2 = {"Ldev/gmitch215/tabroom/api/Judge;", "", "firstName", "", "lastName", "school", "location", "hasParadigm", "", "<init>", "(Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Z)V", "getFirstName", "()Ljava/lang/String;", "getLastName", "getSchool", "getLocation", "getHasParadigm", "()Z", "component1", "component2", "component3", "component4", "component5", "copy", "equals", "other", "hashCode", "", "toString", "tabroom-api"}
)
public final class Judge {
   @NotNull
   private final String firstName;
   @NotNull
   private final String lastName;
   @NotNull
   private final String school;
   @NotNull
   private final String location;
   private final boolean hasParadigm;

   public Judge(@NotNull String firstName, @NotNull String lastName, @NotNull String school, @NotNull String location, boolean hasParadigm) {
      Intrinsics.checkNotNullParameter(firstName, "firstName");
      Intrinsics.checkNotNullParameter(lastName, "lastName");
      Intrinsics.checkNotNullParameter(school, "school");
      Intrinsics.checkNotNullParameter(location, "location");
      super();
      this.firstName = firstName;
      this.lastName = lastName;
      this.school = school;
      this.location = location;
      this.hasParadigm = hasParadigm;
   }

   @NotNull
   public final String getFirstName() {
      return this.firstName;
   }

   @NotNull
   public final String getLastName() {
      return this.lastName;
   }

   @NotNull
   public final String getSchool() {
      return this.school;
   }

   @NotNull
   public final String getLocation() {
      return this.location;
   }

   public final boolean getHasParadigm() {
      return this.hasParadigm;
   }

   @NotNull
   public final String component1() {
      return this.firstName;
   }

   @NotNull
   public final String component2() {
      return this.lastName;
   }

   @NotNull
   public final String component3() {
      return this.school;
   }

   @NotNull
   public final String component4() {
      return this.location;
   }

   public final boolean component5() {
      return this.hasParadigm;
   }

   @NotNull
   public final Judge copy(@NotNull String firstName, @NotNull String lastName, @NotNull String school, @NotNull String location, boolean hasParadigm) {
      Intrinsics.checkNotNullParameter(firstName, "firstName");
      Intrinsics.checkNotNullParameter(lastName, "lastName");
      Intrinsics.checkNotNullParameter(school, "school");
      Intrinsics.checkNotNullParameter(location, "location");
      return new Judge(firstName, lastName, school, location, hasParadigm);
   }

   // $FF: synthetic method
   public static Judge copy$default(Judge var0, String var1, String var2, String var3, String var4, boolean var5, int var6, Object var7) {
      if ((var6 & 1) != 0) {
         var1 = var0.firstName;
      }

      if ((var6 & 2) != 0) {
         var2 = var0.lastName;
      }

      if ((var6 & 4) != 0) {
         var3 = var0.school;
      }

      if ((var6 & 8) != 0) {
         var4 = var0.location;
      }

      if ((var6 & 16) != 0) {
         var5 = var0.hasParadigm;
      }

      return var0.copy(var1, var2, var3, var4, var5);
   }

   @NotNull
   public String toString() {
      return "Judge(firstName=" + this.firstName + ", lastName=" + this.lastName + ", school=" + this.school + ", location=" + this.location + ", hasParadigm=" + this.hasParadigm + ")";
   }

   public int hashCode() {
      int result = this.firstName.hashCode();
      result = result * 31 + this.lastName.hashCode();
      result = result * 31 + this.school.hashCode();
      result = result * 31 + this.location.hashCode();
      result = result * 31 + Boolean.hashCode(this.hasParadigm);
      return result;
   }

   public boolean equals(@Nullable Object other) {
      if (this == other) {
         return true;
      } else if (!(other instanceof Judge)) {
         return false;
      } else {
         Judge var2 = (Judge)other;
         if (!Intrinsics.areEqual(this.firstName, var2.firstName)) {
            return false;
         } else if (!Intrinsics.areEqual(this.lastName, var2.lastName)) {
            return false;
         } else if (!Intrinsics.areEqual(this.school, var2.school)) {
            return false;
         } else if (!Intrinsics.areEqual(this.location, var2.location)) {
            return false;
         } else {
            return this.hasParadigm == var2.hasParadigm;
         }
      }
   }
}

Already we can see some of the reason for the slow runtime.

Kotlin performs metadata comparison at runtime to make sure that the types and versions are correct. This is a very expensive operation, and it can slow down the performance of the program. You can see the metadata in the @Metadata annotation at the top of the class.
Instrinsics preserves null safety and type checking, as well as making sure that variables are equal in the auto-generated code.

These two features are great for making sure that the code is safe and correct, but they come at a cost. The performance of the program is affected by these features, and it can be very slow in some cases.

Conclusion

This was a short analysis about Kotlin's performance. I think that Kotlin is a great language, and I love using it. However, I think that it has a long way to go before it can be considered a high-performance language. The performance of the program is affected by the features that make it safe and correct, and I think that this is a trade-off that is worth making. However, I would like to see some improvements in the performance of the language in the future.

Making Combinatory: Map Search Algorithms

Gregory Mitchell — Mon, 28 Apr 2025 15:10:31 +0000

The Combinatory video game works as a mathematics game where you swipe tiles and combine them into eachother using mathematics operations, trying to get a specific score. This article will detail how I developed the Map Search Algorithm to create randomly generated levels.

Full Function

Here is the full function, according to the open-source paths.kt file in the calculatory repository:

/**
 * The directions a player can make on a grid. Represent up, down, left, and right.
 */
val directions = listOf(
    Pair(0, 1),
    Pair(0, -1),
    Pair(1, 0),
    Pair(-1, 0)
)

/**
 * Find all the possible values that can be obtained by moving on a grid.
 *
 * Worst-case time complexity is `O((4m)^k)`, where `m` is the size of [functions] and k is the number of tiles that can be visited from [sx] and [sy]. This significantly decreases, as the algorithm prunes duplicate results and utilizes
 * coroutines for parallel processing.
 *
 * For example, various testing on the [Mock Example](https://pl.kotl.in/t60amvt1e), which includes a 11x11 grid with 15 functions and 28 empty tiles, took `1.5s` and generated `73,118` values.
 * @param grid The grid to move on, represented as a 2D Double Array. Values of `0` represent an empty tile.
 * @param functions The operations to apply to the values.
 * @param sx The starting x coordinate.
 * @param sy The starting y coordinate.
 * @return A set of all the possible values that can be obtained by moving on the grid.
 * @see <a href="https://pl.kotl.in/t60amvt1e">Mock Example</a>
 */
suspend fun findValues(
    grid: Array<DoubleArray>,
    functions: List<Operation>,
    sx: Int,
    sy: Int
): Set<Double> = coroutineScope {
    val size = grid.size

    require(grid.isNotEmpty()) { "Grid must have at least one row" }
    require(grid[0].isNotEmpty()) { "Grid must have at least one column" }
    require(sx in grid.indices) { "Starting X Coordinate must be within the grid" }
    require(sy in grid[0].indices) { "Starting Y Coordinate must be within the grid" }
    require(grid.all { row -> row.size == size }) { "Grid must be square" }

    val channel = Channel<Double>()
    val visited = mutableSetOf<Pair<Int, Int>>()
    val values = mutableSetOf<Double>()

    suspend fun exploreValue(value: Double, cx: Int, cy: Int, operations: List<Operation>) {
        var hasMoved = false

        directions.forEach directions@{ (dx, dy) ->
            val nx = cx + dx
            val ny = cy + dy

            if (nx < 0.0 || nx >= size) return@directions
            if (ny < 0.0 || ny >= size) return@directions

            if (grid[nx][ny] == 0.0) return@directions
            if ((nx to ny) in visited) return@directions

            visited.add(nx to ny)
            val nv = grid[nx][ny]

            operations.forEach { o ->
                val newValue = o(value, nv)
                if (newValue in values) return@forEach

                values.add(newValue)
                channel.send(newValue)

                val remaining = operations.toMutableList()
                remaining.removeAt(remaining.indexOf(o))
                exploreValue(newValue, nx, ny, remaining)

                hasMoved = true
            }

            visited.remove(nx to ny)
        }

        if (!hasMoved || operations.isEmpty())
            channel.send(value)
    }

    val sv = grid[sx][sy]
    launch {
        exploreValue(sv, sx, sy, functions)
        channel.close()
    }

    for (value in channel)
        values.add(value)

    return@coroutineScope values
}

Analysis

At its barebones, Combinatory level data can be represented as a 2D Number Array:

[
    [ 0, 1, 2, 3, 4 ]
    [ 0, 4, 0, 2, 1 ]
    [ 0, 3, 2, 3, 2 ]
    [ 0, 1, 4, 6, 2 ]
    [ 2, 0, 3, 2, 0 ]
]

We can immediately notice that 0 in this instance represents tiles that are not declared. Therefore, this 5x5 grid example demonstrates that there are some holes in this map.

All Combinatory map data starts as an integer, but can shift to decimal values based on division operations present, which is why the map algorithm uses an Array<DoubleArray> as opposed to an Array<IntArray>. The function also intakes a List<Operation>, which are the operations that are present (addition, subtraction, multiplication, or division), and starting X (sx) and Y (sy) coordinates.

Requirements

The function starts off requiring a few things:

The Array rows or columns can't be empty
Starting coordinates must match valid coordinates in the Array
The Array must be square, or have idential width and height lengths

Implementation

First, the method uses an asynchronous channel to be able to handle multiple paths at once (more on that below), a visited set of pair coordinates to act as an asynchronous mutex to prevent two paths from moving at the sametime, and and the final values set that we will return. The difference between a List and a Set is that a Set is unordered and will reject duplicate values, meaning that we reduce performance overhead and unnecessary space when multiple paths with the same outcome are found. This also works with visited where we only have to know which places were visited.

As we continue to the actual method implementation, the method defines a local function exploreValue which makes a step in any random direction given the current value. This method is called recursively until the player runs out of directions to go to. This reflects the implementation details of the actual game, where you swipe in any direction for any kind of operation until you run out of operations to swipe with. This is demonstrated through looping through both the directions and the operations array, where the former is looped through at random into new asynchronous anlayzers and the latter has its elements removed until it runs out.

After the steps have completed, the channel is closed, and the values are collected into a Set.

Results & Asynchronousity

The function integrates with Kotlin's Suspend functions to reduce time complexity values and explore multiple paths at the same time. It sends the values to a Channel<Double> which then propogates those into a proper Set<Double>, or all of the possible values for every single combination in a map.

Use Cases

While this method is specific to Combinatory, this algorithm is a performative example for how map search can be implemented in Kotlin within a 2D Array. You can utilize this method in your own applications to analyze result data of different maps present in your program.

Conclusion

This was a short but informative explanation about the Map Search Algorithm in the Combinatory Video Game. Stay tuned for more in-depth analysis.

Making Combinatory: Introduction to KorGE

Gregory Mitchell — Mon, 28 Apr 2025 15:09:24 +0000

This will be a short series on how I made the Combinatory video game using the KorGE game engine. I will be going over the basics of the game engine, how I set up the project, and how I implemented the game itself. I will also be going over some of the challenges I faced and how I overcame them.

I have mixed feelings about KorGE. On one hand, it's great, and has a lot of potential. On the other hand, one person maintains the entire thing, which make bugs like
trying to make a working iOS Build take near half a year to even get a response. I mean,
soywiz is a great guy, but he's only one person. I'm sure he's looking for help, but I'm not sure if I'm ready to take on that kind of responsibility, at least when I
have another dozen side projects to work on.

Entry Point

The entry point of the game looks like this:

suspend fun main() = Korge(
    gameId = ID,
    title = TITLE,
    windowSize = SIZE,
    backgroundColor = MAIN_COLOR,
    icon = ICON
) {
    container = sceneContainer(defaultTransition = TRANSITION)
    container.addTo(this)
    loadingSequence(this)

    // UI
    registerScenes()
    title()

    if (Os.CURRENT.isDesktop)
        devMode()
}

ID is set to xyz.calcugames.combinatory, or the package name of the game.
TITLE is set to Combinatory, or the name of the game.
SIZE is set to Size(390, 844), which mimicks the size of a mobile phone.
- The web version automatically fills in the remaining space with MAIN_COLOR.
MAIN_COLOR is set to 0x17558c, or a dark blue.
ICON is the path to the icon of the game stored in the resources folder.

The next TRANSITION is the transitioning scene between the loading screen and the main menu, as well as other scene containers in the game. It's just a default
fade transition.

KorGE makes things really nice when it comes to setting up the game. Just open up a container and boom, you're in the game. No need to worry about setting up
OpenGL or anything like that. It's all done for you.

Loading Sequence

The loading scene looks like this:

class LoadingScene : Scene() {

    override suspend fun SContainer.sceneMain() {
        val text = text("Loading...", 64.0) {
            centerXOnStage()
            y = 100.0
        }

        while (!loaded) {
            text.tween(text::y[height - 100], time = 3.0.seconds, easing = Easing.EASE_IN_OUT)
            text.tween(text::y[100.0], time = 3.0.seconds, easing = Easing.EASE_IN_OUT)
        }
    }

}

KorGE uses Scenes to manage different windows that need to be shown. My loading screen is just a "Loading..." text going up and down until the game is loaded.
This could take anywhere from under a second to near a minute, depending on how fast your computer or phone is. I figured this would satisfy the user's need to
be entertained while the game is loading in a simple game.

KorGE's animation suite is great. It feels like I'm using CSS animations, but in a game engine. I can tween any property of any object, and it will animate
smoothly. I can even tween multiple properties at once, and it will still animate smoothly. It's really nice. The design for using extension functions on
properties is highly clever as well. I can just type text::x or text::color and boom, I'm animating the x position or color of the text. It's amazing.

Level Scene

Finally, I'll show some of the loading operations for the level scene. It's pretty complicated, has a lot of variables, and is arguably highly important. I'm also
not going to reveal anything.

In short, calculatory, or the open source portion with all the algorithms, converts level data into the
LevelZ File Format, which is a level format I created for general use. The game then reads the level data and creates the level
from that.

The auto-generated levels, like the Daily Level and the Endless modes, use multiple seeded values (that are internal so you can't predict them) to generate the
level data. The game then reads the level data and creates the level from that.

Calculatory has an algorithm for getting all of the possible path values in each area:

suspend fun findValues(
    grid: Array<DoubleArray>,
    functions: List<Operation>,
    sx: Int,
    sy: Int
): Set<Double> = coroutineScope {
    val size = grid.size

    require(grid.isNotEmpty()) { "Grid must have at least one row" }
    require(grid[0].isNotEmpty()) { "Grid must have at least one column" }
    require(sx in grid.indices) { "Starting X Coordinate must be within the grid" }
    require(sy in grid[0].indices) { "Starting Y Coordinate must be within the grid" }
    require(grid.all { row -> row.size == size }) { "Grid must be square" }

    val channel = Channel<Double>()
    val visited = mutableSetOf<Pair<Int, Int>>()
    val values = mutableSetOf<Double>()

    suspend fun exploreValue(value: Double, cx: Int, cy: Int, operations: List<Operation>) {
        var hasMoved = false

        directions.forEach directions@{ (dx, dy) ->
            val nx = cx + dx
            val ny = cy + dy

            if (nx < 0.0 || nx >= size) return@directions
            if (ny < 0.0 || ny >= size) return@directions

            if (grid[nx][ny] == 0.0) return@directions
            if ((nx to ny) in visited) return@directions

            visited.add(nx to ny)
            val nv = grid[nx][ny]

            operations.forEach { o ->
                val newValue = o(value, nv)
                if (newValue in values) return@forEach

                values.add(newValue)
                channel.send(newValue)

                val remaining = operations.toMutableList()
                remaining.removeAt(remaining.indexOf(o))
                exploreValue(newValue, nx, ny, remaining)

                hasMoved = true
            }

            visited.remove(nx to ny)
        }

        if (!hasMoved || operations.isEmpty())
            channel.send(value)
    }

    val sv = grid[sx][sy]
    launch {
        exploreValue(sv, sx, sy, functions)
        channel.close()
    }

    for (value in channel)
        values.add(value)

    return@coroutineScope values
}

Pretty cool stuff. I'll show some more later. This was just a short look into the inner workings on the game, which I definetly need to promote more. I'll be
working on that soon. Stay tuned for the next part of the series.

cmdfx v0.1.3 - Physics Engine in the Terminal

Gregory Mitchell — Sat, 19 Apr 2025 02:34:09 +0000

Been through a few revisions since v0.1.0 of the cmdfx Game Engine. This is a short video showcasing the features in v0.1.3 of the engine,
which included some new features in the Physics Engine.

The source code in question is the launcher sample available here:

/**
 * @file launcher.c
 * @author Gregory Mitchell (me@gmitch215.xyz)
 * @date 2025-03-28
 * 
 * This is a simple demo program that shows how to use the Physics Engine for CmdFX.
 * 
 * Simply run the program and watch the object fly around the screen.
 * You can optionally pass a multiplicative modifier to the tick speed as the first parameter
 * to see how fast it will go.
 * 
 * @copyright Copyright (c) 2025
 * 
 */

#include <cmdfx.h>
#include <stdio.h>
#include <stdlib.h>

int main(int argc, char** argv) {
    char** data = Char2DBuilder_createFilled(5, 5, '%');
    data[0][0] = 0;
    data[4][0] = 0;
    data[0][4] = 0;
    data[4][4] = 0;

    CmdFX_Sprite* sprite = Sprite_create(data, 0, 0);

    double speed = 1;
    if (argc > 1) {
        speed = atof(argv[1]);
        if (speed > 0) CmdFX_setTickSpeed((int) (CmdFX_getTickSpeed() * speed));
    }

    if (argc > 2) {
        double friction = atof(argv[2]);
        if (friction >= 0) Engine_setDefaultFrictionCoefficient(atof(argv[2]));
    }

    Canvas_clearScreen();
    Canvas_hideCursor();
    Engine_enableMotionDebug();
    CmdFX_initThreadSafe();

    Canvas_hLine(0, Engine_getGroundY(), Canvas_getWidth(), '-');
    Canvas_hLine(0, 1, Canvas_getWidth(), '-');
    Sprite_draw(2, Canvas_getHeight() - sprite->height - 1, sprite);
    Engine_start();

    CmdFX_Vector* velocity = Vector_create(2, 2);
    Sprite_addForceFor(sprite, velocity, 300 / speed);
    sleepMillis(10000 / speed);

    Engine_end();
    free(velocity);
    Sprite_free(sprite);
    CmdFX_destroyThreadSafe();

    Canvas_showCursor();

    return 0;
}

Breakdown

First, we create a 5x5 sprite with a border of % characters. This is done using the Char2DBuilder_createFilled function, which creates a 2D array of characters filled with the specified character. The 0 at the end removes the corners of the sprite, making it look like a rounded square. The sprite is then created using the Sprite_create function, and we leave the Z-index and ANSI codes at 0 for no unnecessary data.

Next, there are some extra parameters for the program. The first parameter is a speed modifier, which is multiplied by the current tick speed. The tick speed in this case is how fast the Physics Engine processes new information. The tick speed by default is 12, so you can set it to 0.5 to get a slower effect, or 2 for a much faster engine. This allows you to see how fast the object will go if you want to test it out. The second parameter is the default friction coefficient. In Physics, this is used in the calculation for the deceleration of the object when it is moving (or the friction of the object). The default value is 0.5, but you can set it to 0 to see how fast the object will go without any friction. This is useful for testing out the engine and seeing how fast it can go.

Then, we move on to some canvas commands:

Canvas_clearScreen() clears the screen so we get a clean slate to work with.
Canvas_hideCursor() hides the cursor so it doesn't show up on the screen.
Engine_enableMotionDebug() enables the motion debug mode, which shows the motion of each individual sprite drawn on the screen. This is the information tab shown in the top left of the screen shown in the video.
CmdFX_initThreadSafe() initializes the thread-safe mode for the engine. This is used to make sure that the engine is thread-safe and can be used in a multi-threaded environment, which is necessary for the engine to work properly. This method is also automatically called by Engine_start() if you don't want to call it manually.

Now, we draw some visuals on the screen:

Canvas_hLine(0, Engine_getGroundY(), Canvas_getWidth(), '-') draws a horizontal line at the bottom of the screen, which is the ground level for the engine. The Engine_getGroundY() function gets the Y position of the ground level, and Canvas_getWidth() gets the width of the screen.
Canvas_hLine(0, 1, Canvas_getWidth(), '-') draws a horizontal line at the top of the screen, which is the top of the screen.

These are just for visual purposes and doesn't do anything else other than visualize the top and bottom of the screen.

After we draw the sprite with Sprite_draw(2, Canvas_getHeight() - sprite->height - 1, sprite), we start the engine with Engine_start(). This starts the engine and begins processing the physics for the sprite.

The CmdFX_Vector* velocity = Vector_create(2, 2) creates a new vector with the specified X and Y values. This is used to set the velocity of the sprite. The Sprite_addForceFor(sprite, velocity, 300 / speed) adds a force to the sprite for the specified amount of time. The 300 / speed is the amount of time in milliseconds that the force will be applied to the sprite. This is used to make the sprite move in a certain direction. Like in Physics, forces increase the acceleration of the object, and this is how we can make the object move in a certain direction. The sleepMillis(10000 / speed) is used to pause the program for the specified amount of time. This is used to give the sprite time to move before the program ends. The 10000 / speed is the amount of time in milliseconds that the program will pause for. This is used to give the sprite time to move before the program ends.

Finally, we end the engine with Engine_end(), free the memory for the vector and sprite, and destroy the thread-safe mode with CmdFX_destroyThreadSafe(). This is done to clean up any resources that were used by the engine and free up memory. Then, we show the cursor again with Canvas_showCursor() to make sure that the cursor is visible again.

Conclusion

This is a simple demo program that shows how to use the Physics Engine for CmdFX. It is a simple program that shows how to use the engine and how to create a sprite with a border. The program is simple and easy to use, and it is a good starting point for anyone who wants to learn how to use the engine. The engine is still in development, and there are many more features to come in the future. I hope you enjoy using the engine and have fun with it!

Writing Unit Tests in C

Gregory Mitchell — Fri, 11 Apr 2025 13:15:01 +0000

Introduction

We all love C, right? You can basically write anything that you want. But that comes at the cost of you trying to debug everything. So, I'll explain my process of writing unit tests in C, utilizing the CTest Framework with CMake.

The code used in this example is borrowed from the cmdfx library.

Prerequisites

Let's assume your file tree looks something like this:

|CMakeLists.txt
|README.md
|LICENSE
|test/
├── CMakeLists.txt
├── src/
│   ├── test1.c
│   ├── test2.c
│   ├── test3_main.c
│   ├── test3_others.c
│   └── test.h
|include/
└── library.h

In your root CMakeLists.txt, get started with this code:

option(TESTING "Build tests for ${PROJECT_NAME}" ON)
if (TESTING)
    enable_testing()
    add_subdirectory(test)
endif()

This will allow you to start configuring tests when you run cmake .. in the test directory.

Now, in your test/CMakeLists.txt, you can add the following code:

cmake_minimum_required(VERSION 3.16)

include(CTest)

# Tests
function(add_test_executable name)
    set(TEST_NAME "test-${name}")

    # Create the test executable
    add_executable("${TEST_NAME}" "src/${name}.c" "src/test.h")
    target_include_directories("${TEST_NAME}" PRIVATE "${PROJECT_SOURCE_DIR}/include")

    # Link the library to the test executable
    add_dependencies("${TEST_NAME}" "${PROJECT_NAME}")

    # Set the test executable name
    string(REPLACE "_" "/" TEST_EXECUTABLE_NAME ${name}) # Replace underscores with slashes in name
    add_test(NAME ${TEST_EXECUTABLE_NAME} COMMAND "${TEST_NAME}") # Add test command

    # Set the test executable properties if needed
    if (CMAKE_C_COMPILER_ID MATCHES "GNU|Clang")
        # Add coverage flags for GCC/Clang
        target_compile_options("${TEST_NAME}" PRIVATE --coverage -lm -w) # Link with math library and suppress warnings
        target_link_options("${TEST_NAME}" PRIVATE --coverage)
    endif()

    # Set the output directory for the test executable
    set_target_properties(${TEST_NAME} PROPERTIES
        RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin/tests/
    )
endfunction()

# Find Test Files
file(GLOB TESTS "src/*.c")

foreach(TEST_FILE ${TESTS})
    get_filename_component(TEST_NAME ${TEST_FILE} NAME_WE)

    # Call the preceding function to add the test executable
    add_test_executable(${TEST_NAME})
endforeach()

This code will create a function that you can call to add test executables. You can also add the --coverage flag to your tests if you want to.

Writing Tests

`test.h`

test.h is a header file that contains assertion functions that can be used to check the results of your tests. It also contains a function to run all tests.

Here's a modified example of test.h that includes the assertion functions. Now, I usually use a as my actual value instead of my expected value, so feel free to modify this to fit what you usually like to code with:

#ifndef PROJECT_TEST_H
#define PROJECT_TEST_H

// Define the test result strings
#define PASS "PASS"
#define FAIL "FAIL"

#include <stdio.h>
#include <string.h>
#include <math.h>

// Initialize the test counter
static int count = 1;

int assertTrue(int condition) {
    printf("#%d: %s\n", count, condition ? PASS : FAIL);
    if (!condition) {
        printf("#%d: had true, wanted false\n", count);
        count++;
        return 1;
    }

    count++;
    return 0;
}

int assertFalse(int condition) {
    printf("#%d: %s\n", count, !condition ? PASS : FAIL);
    if (condition) {
        printf("#%d: had false, wanted true\n", count);
        count++;
        return 1;
    }

    count++;
    return 0;
}

int assertNull(void* ptr) {
    printf("#%d: %s\n", count, ptr == 0 ? PASS : FAIL);
    if (ptr != 0) {
        printf("#%d: why is <%p> not null\n", count, ptr);
        count++;
        return 1;
    }

    count++;
    return 0;
}

int assertNotNull(void* ptr) {
    printf("#%d: %s\n", count, ptr != 0 ? PASS : FAIL);
    if (ptr == 0) {
        printf("#%d: this pointer shouldn't be null bro\n", count);
        count++;
        return 1;
    }

    count++;
    return 0;
}

int assertEquals(int a, int b) {
    printf("#%d: %s\n", count, a == b ? PASS : FAIL);
    if (a != b) {
        printf("#%d: had <%d>, wanted <%d>\n", count, a, b);
        count++;
        return 1;
    }

    count++;
    return 0;
}

int assertFloatEquals(float a, float b) {
    // use fabs for float comparison because of precision issues
    printf("#%d: %s\n", count, fabs(a - b) < 0.0001f ? PASS : FAIL);
    if (fabs(a - b) >= 0.0001f) {
        printf("#%d: had <%f>, wanted <%f>\n", count, a, b);
        count++;
        return 1;
    }

    count++;
    return 0;
}

int assertDoubleEquals(double a, double b) {
    // use fabs for double comparison because of precision issues
    printf("#%d: %s\n", count, fabs(a - b) < 0.0001 ? PASS : FAIL);
    if (fabs(a - b) >= 0.0001) {
        printf("#%d: had <%f>, wanted <%f>\n", count, a, b);
        count++;
        return 1;
    }

    count++;
    return 0;
}

int assertNotEquals(int a, int b) {
    printf("#%d: %s\n", count, a != b ? PASS : FAIL);
    if (a == b) {
        printf("#%d: had <%d>, didn't want <%d>\n", count, a, b);
        count++;
        return 1;
    }

    count++;
    return 0;
}

int assertGreaterThan(int a, int b) {
    printf("#%d: %s\n", count, a > b ? PASS : FAIL);
    if (a <= b) {
        printf("#%d: wanted <%d> to be greater than <%d>\n", count, a, b);
        count++;
        return 1;
    }

    count++;
    return 0;
}

int assertLessThan(int a, int b) {
    printf("#%d: %s\n", count, a < b ? PASS : FAIL);
    if (a >= b) {
        printf("#%d: wanted <%d> to be less than <%d>\n", count, a, b);
        count++;
        return 1;
    }

    count++;
    return 0;
}

int assertIn(double value, double min, double max) {
    printf("#%d: %s\n", count, value >= min && value <= max ? PASS : FAIL);
    if (value < min || value > max) {
        printf("#%d: expected <%f> to be in range <%f> to <%f>\n", count, value, min, max);
        count++;
        return 1;
    }

    count++;
    return 0;
}

int assertPointersMatch(void* a, void* b) {
    printf("#%d: %s\n", count, a == b ? PASS : FAIL);
    if (a != b) {
        printf("#%d: expected pointers <%p> and <%p> to match\n", count, a, b);
        count++;
        return 1;
    }

    count++;
    return 0;
}

int assertStringsMatch(char* a, char* b) {
    if (a == 0 || b == 0) {
        printf("#%d: %s\n", count, a == b ? PASS : FAIL);
        if (a != b) {
            printf("#%d: expected strings <%s> and <%s> to match\n", count, a, b);
            count++;
            return 1;
        }
    }

    printf("#%d: %s\n", count, strcmp(a, b) == 0 ? PASS : FAIL);
    if (strcmp(a, b) != 0) {
        printf("#%d: expected strings <%s> and <%s> to match\n", count, a, b);
        count++;
        return 1;
    }

    count++;
    return 0;
}

#endif

Other Test Files

For this example, I'm going to modify an example from the CmdFX testing suite. Now, you can create your test files.

#include <stdio.h>

#include "cmdfx/core/sprites.h"
#include "test.h"

int main() {
    int r = 0;

    CmdFX_Sprite* sprite = Sprite_createFilled(5, 5, '&', 0, 0);
    Sprite_draw(4, 4, sprite);

    r |= assertEquals(sprite->x, 4);
    r |= assertEquals(sprite->y, 4);

    Sprite_moveTo(sprite, 2, 2);

    r |= assertEquals(sprite->x, 2);
    r |= assertEquals(sprite->y, 2);

    Sprite_moveBy(sprite, 1, 1);

    r |= assertEquals(sprite->x, 3);
    r |= assertEquals(sprite->y, 3);

    return r;
}

This test file creates a sprite and moves it around. It uses the assertion functions to check if the sprite's position is correct after each move.
You can create as many test files as you want, and they will all be compiled into separate executables. You can also use the assert functions in any of your test files.

Running Tests

To run the tests, you can use the following command:

ctest --output-on-failure

This will run all the tests and show the output for any failed tests. You can also use the --coverage flag to generate a coverage report.

Conclusion

Writing unit tests in C can be a bit tricky, but with the right tools and techniques, it can be done easily. The CTest framework with CMake makes it easy to create and run tests, and the assertion functions in test.h make it easy to check the results of your tests. I hope this guide helps you get started with writing unit tests in C!

Reverse-Engineering Cookies with Ktor and Ksoup

Gregory Mitchell — Sun, 06 Apr 2025 19:20:30 +0000

Introduction

Tabroom is a website used by the Speech & Debate community to check tournament data, read ballots, look at judges, and basically serves as the primary hub of managing competitions. It was created by Chris Palmer as a hobby project and is now property of the National Speech & Debate Association.

As I've continued development on a TabroomAPI, which scrapes the HTML content of the website to provide readable data, I eventually found myself having to introduce an authentication suite for accessing new content on the website. Now, Tabroom has this neat little website called api.tabroom.com that has a lot of the same data as the main website, but in a much more usable format.

The only problem was that entire API... isn't actually accessible to the public, nor is it widely documented outside of its OpenAPI specification. Most of its methods are for specifically marked accounts. This means that I was presented with a dilemma: Either drop the authentication suite, or somehow reverse-engineer the Set-Cookie header when logging in through the HTML page to retrieve a session ID.

And I'm no quitter, so here's how I did it.

Prerequisites

TabroomAPI is built on top of Ktor, a Kotlin-based HTTP client and server framework. This means that I needed to use Ktor's HttpClient to make the requests to the Tabroom API. If you don't have Ktor set up, you can follow the Ktor documentation to get started.

On top of this, because it scrapes HTML content, I also needed to use the Jsoup and Ksoup libraries to parse the HTML content and extract the necessary values. Because it's built on top of Ktor, it's available on multiple plaforms, meaning I needed to find different libraries to parse the HTML content on different platforms, and use different Ktor engines. For example, on Android, it uses the OkHttp engine, while on iOS, it uses the Darwin engine, and on the JVM, it uses the Java engine introduced in JDK11. You can look at the full build.gradle.kts file to see the dependencies and how they are set up.

As a result, it uses its own Document and Element classes as wrappers built on top of these libraries.

// Minimalistic document library only for the things I need
internal class Document(
    val url: String,
    val html: String
) {

    val body: Element
        get() = querySelector("body") ?: throw IllegalStateException("Document does not have a body element")

    val bodyElements: String
        get() = body.innerHTML
            .replace(Regex("<script\\b[^>]*>([\\s\\S]*?)</script>"), "")
            .replace(Regex("<style\\b[^>]*>([\\s\\S]*?)</style>"), "")

    val head: Element
        get() = querySelector("head") ?: throw IllegalStateException("Document does not have a head element")

}

// Performs a CSS Query Selection on the document
internal expect fun Document.querySelectorAll(selector: String): List<Element>
internal fun Document.querySelector(selector: String): Element? = querySelectorAll(selector).firstOrNull()
internal fun Document.getElementById(id: String): Element? = querySelector("#$id")
internal fun Document.getElementsByClassName(className: String): List<Element> = querySelectorAll(".$className")
internal fun Document.inputValue(name: String): String? {
    val input = querySelector("input[name=$name]") ?: return null
    return input["value"] ?: input["checked"]
}

// Minimilastic element library only for the things I needs
internal class Element(
    val tagName: String,
    val innerHTML: String,
    val textContent: String,
    val attributes: Map<String, String>,
    val children: List<Element>
) {
    operator fun get(attribute: String): String? = attributes[attribute]
}

Here's an example implementaton on the JVM:

import org.jsoup.Jsoup

private fun org.jsoup.nodes.Element.convert(): Element {
    return Element(
        tagName = tagName(),
        innerHTML = html(),
        textContent = text(),
        attributes = attributes().asList().associate { it.key to it.value },
        children = children().map { it.convert() }
    )
}

internal actual fun Document.querySelectorAll(selector: String): List<Element> {
    val doc = Jsoup.parse(html)
    return doc.select(selector).map { it.convert() }
}

Now that we have all of that settled, let's get started.

Inspecting the HTTP Request

The first thing I needed to figure out what how it naturally did it. It's pretty simple: Tabroom will send your username and password in plain text to the server, along with a SHA and Salt with the password. There were other parameters that were completely unrelated, but I didn't need them. The important part was that the server would respond with a Set-Cookie header, which is what I needed to get the session ID.

Looking through the Firefox network tab, this was pretty clear:

The TabroomToken value is a URL-encoded session ID, that is sent along with each header in a Cookie request to the website to signify that a user is logged in.

Retrieving the Token

This is what the HTML form looks like on Tabroom:

<form name="login" action="/user/login/login_save.mhtml" method="post" class="signin">
    <input type="hidden" name="salt" value="aBhZ7Ec3">

    <input type="hidden" name="sha" value="$6$aBhZ7Ec3$zymKdLO6lp4eBarEM2bvauJyuIAxHgUNKDF3mZFzlBA0HmA2WuTwAu2Y89akiPPSROLvU.RNC/uPRALVi6Ug4/">

    <div class="full centeralign flexrow martop">
        <span class="ninetenths marno padvertno padleft padright">
            <input type="text" id="username" name="username" class="noresize full" value="" autocomplete="on" placeholder="Email address">
        </span>
    </div>

    <div class="full centeralign flexrow">
        <span class="ninetenths marno padvertno padleft padright">
            <input id="password" name="password" class="noresize full" type="password" value="" placeholder="Password">
        </span>
    </div>

    <div class="full centeralign flexrow">
        <span class="ninetenths marno padvertno padleft padright">
            <input type="submit" value="Login" class="noresize full">
        </span>
    </div>
</form>

Before you say I "leaked anything" - the salt and sha values don't actually have any real security value. They are unique to every browser tab and change when you refresh the page every time. Because Tabroom is open source, you can see that these values are completely random and are used to generate the Session ID. Of course to actually create the session ID, you need the login credentials, which I obviously can't share. But, if you have a Tabroom account, you can easily get this information by inspecting the network tab in your browser.

In response, I created two Kotlin methods: One to get these randomly generated values, and the other to use my Tabroom Credentials to retrieve a Session ID.

// Use an engine from different platforms
internal expect val engine: HttpClientEngine

// Initialize our client
internal val client
    get() = HttpClient(engine) {
        expectSuccess = false
        followRedirects = false
    }

// Internal method to retrieve a document by its URL
internal suspend fun String.fetchDocument(useToken: Boolean = true): Document {
    val res = client.get(this) {
        headers {
            append("User-Agent", "Ktor HTTP Client, Tabroom API v1")

            append("Accept", "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8")
            append("Accept-Language", "en-US,en;q=0.9")
            append("Connection", "keep-alive")
            append("Upgrade-Insecure-Requests", "1")
        }

        if (isLoggedIn && useToken)
            cookie("TabroomToken", token!!) // Use the "Cookie" function to set the cookie
    }

    if (!res.status.isSuccess()) throw IOException("Failed to fetch document: ${res.status}\n${res.bodyAsText(Charsets.UTF_8)}") // Print out the error message

    val text = res.bodyAsText(Charsets.UTF_8)
    return Document(this, text)
}

// Platform-specific url encoding/decoding
expect fun encodeURL(url: String): String
expect fun decodeURL(url: String): String


/**
 * Whether the API has currently stored a Session ID.
 */
val isLoggedIn: Boolean
    get() = token != null

/**
 * The current Session ID for the API.
 */
var token: String? = null
    private set

private suspend fun getSaltAndSha(): Pair<String, String> {
    val document = "https://www.tabroom.com/user/login/login.mhtml".fetchDocument() // Read and Parse HTML
    val salt = document.inputValue("salt") ?: throw IllegalStateException("Salt not found in document")
    val sha = document.inputValue("sha") ?: throw IllegalStateException("SHA not found in document")

    return Pair(salt, sha)
}

/**
 * Logs in to Tabroom with the given username and password.
 *
 * This function performs a login request to Tabroom and stores the authentication token in the `token` variable.
 * Tokens represent the Session ID and are valid for 1,024 hours, or roughly 42 days.
 * 
 * @param username The username to log in with.
 * @param password The password to log in with.
 * @return True if the login was successful, false otherwise.
 * @throws IOException If the login request fails.
 */
@JsName("loginAsync")
@JvmName("loginAsync")
suspend fun login(username: String, password: String): Boolean {
    val (salt, sha) = getSaltAndSha()

    val res = client.submitForm(
        "https://www.tabroom.com/user/login/login_save.mhtml",
        parameters {
            append("tourn_id", "")
            append("key", "")
            append("salt", salt)
            append("sha", sha)
            append("category_id", "")
            append("return", "")
            append("username", username)
            append("password", password)
        }
    ) {
        headers {
            append("User-Agent", "Ktor HTTP Client, Tabroom API v1")
            append("Content-Type", "application/x-www-form-urlencoded")
            append("Accept", "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8")
        }
    }

    // Redirect value of 302 means sucess; Don't be fooled by a 200 or something else
    if (res.status.value != 302) throw IOException("Unexpected status code: ${res.status}")

    val cookie = res.setCookie() // Retrieve the value of 'Set-Cookie'
    if (cookie.isEmpty()) return false

    val tabToken = cookie.firstOrNull { it.name == "TabroomToken" }?.value // Get the value of 'TabroomToken'
    if (tabToken == null) return false
    if (tabToken.isEmpty()) throw IllegalStateException("TabroomToken is empty")

    token = decodeURL(tabToken) // Set the token variable to the decoded value
    return true
}

This is a pretty long chunk of code, but the comments should be self-explanatory. We first fetch the HTML document from the login page, and then parse the salt and sha values from the HTML. We then use these values to create a POST request to the login page with our username and password. If the request is successful, we retrieve the Set-Cookie header and extract the TabroomToken value, which is our session ID.

The login function returns a boolean value indicating whether the login was successful or not. If the login was successful, the token variable is set to the session ID, which can be used for subsequent requests to the Tabroom API.

Conclusion

Now that I have a proper login function, I can use it to authenticate with the Tabroom API and retrieve data from the website. This is a pretty simple example of how to reverse-engineer a cookie using Ktor, but it can be applied to other websites as well.

Some example applications are in the ginormous fetcher.kt file available on GitHub. I hope this article was useful to you on how we could reverse-engineer cookies using Ktor.

Using WakaTime to Boost Productivity

Gregory Mitchell — Sun, 06 Apr 2025 17:44:22 +0000

Note: I am not associated with WakaTime, nor did I get paid anything to write this. I just think it's a great tool that I wanted to share with you. Here's my WakaTime profile for reference. I have over 2,500 hours logged in programming as of writing this article since I installed the application in February 2022.

What is WakaTime?

WakaTime is a productivity tool that tracks the time you spend coding in various programming languages and IDEs. It provides detailed statistics on your coding habits, including the amount of time spent on different projects, languages, and even specific files. This data can help you identify patterns in your work and make informed decisions about how to improve your productivity.

I really enjoy it because I like to see how I've progressed as a programmer over the years. I spent a lot of time in Java around the time I discovered the tool, which is why I have over 1,200 hours in that language alone. That statistic is not only a good thing to put on my CV, but also as a general tracker to see how much I actually spend coding. I also like to see how much time I spend on different projects, which is a great way to see how much time I spend on my own projects versus schoolwork.

How to Use WakaTime

WakaTime comes as a plugin in various IDEs and text editors, including Visual Studio Code, IntelliJ IDEA, and Sublime Text. It's also a browser plugin, which is why my "Other" language is around 300 hours, since it tracks how much time I spend reading and reviewing GitHub issues and pull requests. You can install the plugin for your preferred IDE or text editor, and it will automatically start tracking your coding activity.

Is it a Keylogger?

No. All of WakaTime is open source, by the way, if you really think it's that deep. Their FAQ also details all of the safety measures you can take if you're afraid your file paths or project names will get out.

Deleting your account also wipes your data across all their servers. And, most of this "sensitive data" isn't actually public. What is public makes the application even better, in my opinion, which is why I like it much better than other code tracking statistics.

The Competitive Aspect

WakaTime also features a leaderboard system based on general coding time for that week, and the coding time in that week for a speicfic programming language. This in of itself is very interesting, as in introduces an anonymous yet competitive aspect to progamming, encouraging me to work more when I don't want to. It's pretty nice.

Other Nice Things

You could compare WakaTime to the other thousands of code stat tracking tools out there, but there's a few reasons why I like WakaTime over the others.

For one, it's open source, and the data is stored on your own servers. You can also self-host it if you want to, which is a nice feature. The other tools I've seen are either not open source or don't have the same level of detail in their statistics. Second, they have a really good way of visualizing all of your data. The graphs and charts look really sleek and are easy to read. My third and favorite thing that they do is that they can send all of this to your email so you don't have to remember to open up the app all the time. They have a nice, clean way of detailling a daily, weekly, monthly, even yearly reports about your leaderboard status and your hours coded.

These all make WakaTime a great tool for tracking your coding activity and improving your productivity. The data is easy to read and understand, and the competitive aspect adds an extra layer of motivation to keep coding.

Other Not so Nice Things

No good application is perfect. The bad ones pretend they are, and WakaTime doesn't. For one, their language detection system has always been pretty interesting. You can kind of control what language it is in your user settings, which means that there is probably always a fight between what a *.m or *.scs file is. I overrode the latter while I was developing StarCosmetics, and when I looked at the leaderboard, around 10,000+ people were now developing structures for my project. I don't know if that's a good thing or a bad thing, but it was interesting to see that I was the only one who had that language set to StarCosmetics. I think it would be nice if they had a way to override the language detection system for specific files, but I don't know how they would do that.

Another thing is that their plans are a little skewed. Free is free, and it is what it is. Basic doesn't really give you much of anything, and Premium gives you everything. I think Basic is a little overproced and Premium is a little underpriced.

I also joined in a weird time when they started making things available in the free plan now only available in the premium/basic plans. My old email reports were grandfathered in, but I technically can't modify them in any way because they are only available in the Basic plan. Because of how old the platform looks, it's probably built with an older tech stack, meaning that there have been bugs here or there.

Speaking of bugs, my biggest gripe is the fact that their web plugins are a little... terribly designed. For example, I use Cloudinary for one project, but haven't been able to figure out how to link the two together. In addition, when you use the github.dev vs a GitHub Codespace area, it appends [GitHub] to your project name, which is annoying.

Conclusion

Even with my few gripes, WakaTime is a great tool for tracking your coding activity and improving your productivity. It's easy to use, provides detailed statistics, and has a competitive aspect that can help motivate you to code more. If you're looking for a way to boost your productivity and track your coding habits, I highly recommend giving WakaTime a try. You can find more information on their website.

How to Name a Project

Gregory Mitchell — Mon, 31 Mar 2025 02:41:17 +0000

How do you properly name a programming project?

This is one of the most pressing issues for developers in 2025. This is arguably more important than AI replacing everything or your favorite language dying.

No: Mythological Figures

One of my golden rules is that your name needs to make sense. Naming a communication network "Hermes" may seem appealing, but it could mean a number of things. Usually you want your project to be visible in your search engine, because you want your project to be what developers need.

Why?

Because that's the goal of open source: You want your developers to use your project because it's good. Good projects have good names that make them stand out. That's fundamentally why you should avoid mythological figures: they make your project feel unoriginal.

Yes: Word Combinations

Using word combinations may seem weird. "BattleCards," "StarCosmetics," and "Novaconomy" were all terrible names I thought of during my Minecrafting phase. But they stood out on their own. Now, they're (somewhat) successful plugins with a combined ~5,000 downloads on Spigot, and ~10,000 across all platforms.

Usually weird is memorable, which is good. You want developers to remember your project. Sure, they can always star it for later, but not everyone does that. Developers see hundreds of git repositories every day, and the ones that remember yours are going to use it.

Think about all the times you've came across a GitHub project that fit exactly what you needed, but you couldn't remember how to find it, so you found a different one. Sometimes search history is your friend, and sometimes it can reveal to your friends that you really hate Go.

No: Brand-Exact

This one is probably the most controversial, even in an enterprise space. You shouldn't name your open-projects after your business brand.

This is liekly due to the psychology of how developers view the companies that maintain them: sure, they could be sponsoring every contributor to the project, but they don't. In addition, the most hardcore open source contributors are mostly anti-capitalist and pro-freeware, which may go against your employer's values. I'm not criticizing or revealing any political views here, I'm just stating the facts. Developers like open-source projects that feel like open source projects, and your project should reflect that initiative.

If you want me to be more specific, don't name your project after your company's mascot or logo word for word. More on that below.

Yes: Brand-Inspired

This is different than the above. You want your name to stand on its own, but if you're working for a company, you still need to put food on the table, so it should be associated with the company, not representative of the company.

If this is confusing, I'll give you an example. I'm working on a game under my company, Calculus Games, named Combinatory (click to play). The actual game is going to be closed-source (because of env vars), but I want to open-source as much as possible. The open source portion is named "calculatory" instead of "combinatory-public" simply because it's a brand that stands on its own independent of the "combinatory" brand name. The game, which will eventually be a for-profit inspired game, will not overshadow the open-source portion.

Conclusion

These are some short guidelines on naming your project. Listen to them, or don't. No one really cares. A name should reflect the developer's own personal choice, not what some random kid says on his website. Name your project however you want to, and do whatever you think works best for you.