DEV Community: tapadyuti chatterjee

Making HTTP Fail on Purpose: Building a Small Chaos Library for Java - Flaky HTTP

tapadyuti chatterjee — Fri, 28 Aug 2026 03:46:54 +0000

I recently built and open-sourced Flaky HTTP, a small Java 11 library for deliberately making HTTP calls less reliable.

That may sound like an unusual goal. Most of the time, we work hard to make HTTP calls reliable. We add retries, timeouts, circuit breakers, fallbacks, caches, and monitoring. But eventually we need to answer a more difficult question:

How do we know any of that behavior actually works?

The original idea was simple: wrap Java's standard HttpClient, add controlled latency or synthetic HTTP errors to selected requests, and leave the rest of the application unchanged.

That simple idea led to a few interesting decisions around API design, asynchronous cancellation, response body handling, deterministic testing, and the boundary between application-level failure injection and real network chaos.

This article goes beyond a launch announcement. I want to explain why I built the library, how it works internally, where it is useful, and where it is deliberately limited.

TL;DR

Flaky HTTP is a lightweight wrapper around Java 11's java.net.http.HttpClient.

It can:

add fixed or random latency;
return synthetic HTTP errors with a configurable probability;
target requests using a full-URI regular expression;
handle synchronous and asynchronous calls;
propagate cancellation for delayed asynchronous work; and
run without runtime dependencies beyond Java 11.

The Maven coordinate is com.tapadyuti:flaky-http:1.0.0. The shortest useful test setup is a deterministic failure:

FlakyConfig config = FlakyConfig.builder()
        .failureRate(1.0)
        .errorStatus(503)
        .build();

Every targeted call now returns an empty synthetic 503 response without reaching the network. Replace 1.0 with 0.0 and add LatencyStrategy.fixed(500) when the test should exercise slowness without an HTTP error.

It is intended for integration tests, resilience tests, local development, and controlled demonstrations. It is not a replacement for a network proxy or a full chaos-engineering platform.

AI note: AI helped structure and polish this article. The underlying architecture, codebase, and implementation decisions are entirely my own.

The problem I wanted to solve

The successful path of an HTTP integration is usually easy to test.

Start a test server, return 200 OK, deserialize the response, and assert the result. But production dependencies rarely fail in one neat way. They become slow. They return 429, 500, or 503. They recover after a retry. They stay unhealthy long enough to open a circuit breaker. Sometimes one endpoint fails while everything else continues to work.

The surrounding application is expected to handle all of this correctly.

In many test suites, however, the failure setup becomes more complicated than the behavior being tested. We may need to modify a mock server, add proxy rules, change container networking, or create one-off test doubles for every client abstraction.

I wanted something smaller for a common case:

My application already uses Java's HttpClient. I want selected calls to become slow or return an error, without changing the real service.

That became the scope of Flaky HTTP.

The basic model

The library uses composition. An application gives FlakyHttpClient a real HttpClient and an immutable configuration.

Application
    |
    v
FlakyHttpClient
    |
    +-- URI does not match ----------> Real HttpClient
    |
    +-- URI matches
          |
          +-- apply latency
          |
          +-- failure selected ------> Synthetic HTTP response
          |
          +-- otherwise -------------> Real HttpClient

For a targeted request, latency is applied first. The client then makes a failure decision. If failure is selected, it returns a synthetic response without touching the network. Otherwise, it delegates the original request and body handler to the real client.

A minimal configuration looks like this:

FlakyConfig config = FlakyConfig.builder()
        .failureRate(0.30)
        .latency(LatencyStrategy.random(100, 500))
        .errorStatus(503)
        .targetUrls("https://api\\.example\\.com/.*")
        .build();

This configuration adds between 100 and 500 milliseconds of latency to matching requests. After the delay, 30 percent of those requests receive a synthetic 503 Service Unavailable. The remaining requests go to the real service.

The code using it remains close to normal HttpClient code:

HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://api.example.com/orders/42"))
        .GET()
        .build();

try (FlakyHttpClient client =
             new FlakyHttpClient(HttpClient.newHttpClient(), config)) {
    HttpResponse<String> response =
            client.send(request, HttpResponse.BodyHandlers.ofString());

    System.out.println(response.statusCode());
}

Why I chose composition

One of the first design decisions was whether FlakyHttpClient should behave as another HttpClient subtype or be an explicit wrapper.

I chose an explicit composition-based wrapper.

This makes the boundary visible. Code that opts into failure injection receives a FlakyHttpClient; code that should always use the original client can continue using HttpClient. It also keeps the library focused on the two operations it needs to control: send and sendAsync.

There is a tradeoff. A FlakyHttpClient cannot be passed directly to a method that requires an HttpClient. In a larger application, I would normally place HTTP access behind an application-owned interface anyway. That interface can then be backed by the real client or by the flaky wrapper in tests.

The key word is explicit. Failure injection should not quietly appear in unrelated calls.

Synthetic responses still need to respect `BodyHandler`

Returning an integer status code is easy. Returning a useful HttpResponse<T> is more subtle.

Java's HTTP API lets the caller decide how a response body should be converted:

HttpResponse.BodyHandlers.ofString()
HttpResponse.BodyHandlers.ofByteArray()
HttpResponse.BodyHandlers.discarding()

If Flaky HTTP simply cast an empty string to T, it would work for one handler and fail for others. The synthetic path therefore applies the caller's real BodyHandler to response metadata, creates its BodySubscriber, and completes that subscriber with an empty body.

As a result:

ofString() receives "";
ofByteArray() receives an empty byte array;
discarding() receives its normal result; and
a custom handler still controls conversion.

The synthetic response also includes Content-Length: 0, the original request and URI, the configured error status, and the wrapped client's preferred HTTP version.

This was one of the most important implementation details. A failure-testing utility should not introduce a completely different response contract from the API it wraps.

Synchronous and asynchronous latency are different problems

For synchronous calls, artificial latency is straightforward. The calling thread sleeps before the failure decision or real network call. If it is interrupted, the request is not delegated and InterruptedException is propagated.

The asynchronous path needed more care.

Calling Thread.sleep inside sendAsync would make an asynchronous API block the caller, which defeats the purpose. Flaky HTTP instead uses a ScheduledExecutorService to begin the next step after the configured delay.

client.sendAsync(request, HttpResponse.BodyHandlers.ofString())
        .thenAccept(response ->
                System.out.println(response.statusCode()))
        .join();

Cancellation also has two possible states:

The artificial delay is still pending.
The delay has finished and the real HTTP request has started.

Cancelling the returned CompletableFuture cancels the scheduled delay when possible. If delegation has already started, it attempts to cancel the delegate future as well.

The default constructor creates a small internal daemon scheduler. Because that is a resource with a lifecycle, FlakyHttpClient implements AutoCloseable and works naturally with try-with-resources.

Applications that already manage executors can supply their own scheduler:

ScheduledExecutorService scheduler =
        Executors.newScheduledThreadPool(2);

try {
    try (FlakyHttpClient client =
             new FlakyHttpClient(HttpClient.newHttpClient(), config, scheduler)) {
        client.sendAsync(request, HttpResponse.BodyHandlers.ofString()).join();
    }
} finally {
    scheduler.shutdown();
}

The ownership rule is intentionally simple: the client closes a scheduler it creates, but never closes one supplied by the caller.

Deterministic tests and probabilistic experiments

A random failure rate is useful when exploring system behavior locally. It is usually a poor foundation for a repeatable automated test.

For tests, the boundary values are more useful:

FlakyConfig alwaysUnavailable = FlakyConfig.builder()
        .failureRate(1.0)
        .errorStatus(503)
        .targetUrls("http://localhost:8080/orders/.*")
        .build();

A rate of 1.0 always returns the synthetic error. A rate of 0.0 never injects an error, but can still add latency. Both configurations are deterministic.

For example, an integration test can make the upstream orders endpoint consistently unavailable and verify the application's fallback path:

@Test
void usesFallbackWhenOrdersApiIsUnavailable() throws Exception {
    FlakyConfig chaos = FlakyConfig.builder()
            .failureRate(1.0)
            .errorStatus(503)
            .targetUrls("http://localhost:8080/orders/.*")
            .build();

    HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("http://localhost:8080/orders/42"))
            .GET()
            .build();

    try (FlakyHttpClient client =
             new FlakyHttpClient(HttpClient.newHttpClient(), chaos)) {
        HttpResponse<String> response =
                client.send(request, HttpResponse.BodyHandlers.ofString());

        OrderResult result = orderService.handle(response);

        assertEquals(503, response.statusCode());
        assertTrue(result.isFallback());
    }
}

OrderResult and orderService represent the application code under test. The important part is that the request never needs a cooperating failure mode from the local server.

For exploratory testing, a value such as 0.2 or 0.3 is useful. It creates a mixed stream of successful and unsuccessful calls that can expose assumptions in logs, metrics, retry behavior, and user-facing error handling.

It was a good reminder that deterministic testing and random fault injection solve related but different problems. The library supports both, but the caller should choose deliberately.

Targeting only the dependency that matters

Most applications call more than one endpoint. Making every request fail can hide the behavior we actually want to observe.

targetUrls accepts a Java regular expression and matches it against the complete URI string:

// Every path on one host
.targetUrls("https://api\\.example\\.com/.*")

// Only the payments endpoint, with an optional query string
.targetUrls("https://api\\.example\\.com/payments(?:\\?.*)?")

// Any URI containing /experimental/
.targetUrls(".*/experimental/.*")

The full-match behavior matters. A pattern such as /payments does not search inside the URI. Callers need .* when they want a partial match.

Requests that do not match bypass both latency and failure injection.

This makes a few useful scenarios possible:

Scenario	Injection	What it can verify
Retry policy	Repeated `503` responses	Attempt limits, backoff, and eventual failure
Rate limiting	A synthetic `429`	Backpressure and retry suppression
Circuit breaker	Guaranteed `500` or `503`	Open, half-open, and recovery behavior
Fallback or cache	Failure on one endpoint	Degraded or cached responses are selected
Timeout handling	Fixed latency beyond an app deadline	Cancellation, cleanup, and error propagation
Observability	Random delay and intermittent errors	Logs, traces, metrics, dashboards, and alerts
Bulkhead behavior	Concurrent delayed async calls	A slow dependency does not consume unrelated capacity
Local demos	Predictable failures	Error states can be reproduced without changing a service

The library is small, but its most valuable use cases sit outside the library. They are tests of the application behavior surrounding an unreliable dependency.

Here are three compact configurations I expect to use most often:

// Verify retry, circuit-breaker, or fallback behavior
FlakyConfig.builder()
        .failureRate(1.0)
        .errorStatus(503)
        .build();

// Verify an application-level timeout without injecting an error
FlakyConfig.builder()
        .failureRate(0.0)
        .latency(LatencyStrategy.fixed(1_000))
        .build();

// Verify rate-limit handling only for the payments API
FlakyConfig.builder()
        .failureRate(1.0)
        .errorStatus(429)
        .targetUrls("https://api\\.example\\.com/payments(?:\\?.*)?")
        .build();

These boundary-value configurations are predictable enough for CI. I would reserve random latency and partial failure rates for exploratory tests, longer-running resilience suites, and demonstrations.

A subtle timeout boundary

Artificial latency happens before the real request is delegated to HttpClient.

That means a timeout configured directly on HttpRequest does not include the injected pre-request delay. The wrapped client has not seen the request yet.

When I want to test an end-to-end deadline, I apply the timeout around the complete operation. For asynchronous code, that could be a future timeout:

client.sendAsync(request, HttpResponse.BodyHandlers.ofString())
        .orTimeout(300, TimeUnit.MILLISECONDS)
        .join();

This makes the caller observe an application-level timeout around the whole future. One more detail matters: orTimeout completes a future exceptionally; it does not mean the underlying work was cancelled. A test that specifically verifies cancellation should retain the original future and call cancel(true), which lets Flaky HTTP cancel a pending artificial delay and attempt to cancel a delegated request.

This distinction is small but important. A test should be clear about whether it is exercising the transport's request timeout, the application's complete-operation deadline, or explicit cancellation.

What Flaky HTTP intentionally does not simulate

Flaky HTTP sits immediately above HttpClient. It is not a proxy and it does not alter packets on the wire.

It can simulate application-visible latency and HTTP error responses. It cannot faithfully reproduce:

DNS resolution failures;
connection refusal;
TLS negotiation errors;
connection resets;
truncated response bodies;
malformed HTTP;
bandwidth restrictions; or
packet loss.

Those tests need a different layer: a fault-injecting proxy, a container networking tool, a faulty test server, or a network emulator.

I think this limitation is healthy. Small libraries are more useful when their boundary is explicit. Flaky HTTP covers the cases where the application needs to observe a slow call or an HTTP error. It does not pretend that every distributed-systems failure is equivalent to a 503.

A few decisions that paid off

A few implementation choices had an outsized effect on the final library.

1. Immutable configuration

FlakyConfig is built once and then shared safely. The failure rate, latency strategy, error status, and URL pattern cannot change underneath an in-flight request.

2. Validation at the boundary

Failure rates must be finite values from 0.0 through 1.0. Error statuses must be between 400 and 599. The built-in latency factories reject negative values and invalid ranges; custom strategies are required by their API contract to return a non-negative delay. Invalid regular expressions fail during configuration rather than during a later request.

3. No runtime dependencies

The implementation uses Java 11's HTTP, concurrency, and flow APIs. Keeping the runtime dependency list empty makes the library easier to introduce into test suites without creating version conflicts.

4. Explicit scheduler ownership

The constructor determines who owns the scheduler, and close() follows that decision. This avoids both leaked internal threads and surprising shutdowns of shared application infrastructure.

5. Honest documentation of edge cases

The README and Javadocs describe full-URI matching, body-handler behavior, timeout boundaries, asynchronous cancellation, and the difference between synthetic HTTP failures and network faults.

For a testing library, those details are part of the API. A false assumption in a failure test can be worse than having no test at all.

Installation

The Maven coordinates for version 1.0.0 are:

<dependency>
    <groupId>com.tapadyuti</groupId>
    <artifactId>flaky-http</artifactId>
    <version>1.0.0</version>
</dependency>

For Gradle:

testImplementation("com.tapadyuti:flaky-http:1.0.0")

The project requires Java 11 or later. The repository also includes a comprehensive demo covering fixed latency, random latency, URL targeting, guaranteed failures, asynchronous calls, and a caller-owned scheduler. The test suite additionally verifies cancellation of a pending asynchronous delay.

Flaky HTTP is available under the Apache License 2.0. Focused issues and pull requests are welcome, especially when they include a reproducible failure scenario and tests.

git clone https://github.com/tapadyutichatterjee/flaky-http.git
cd flaky-http
mvn clean verify
java -cp target/classes com.tapadyuti.flakyhttp.FlakyHttpDemo

What I would improve next

The current API is deliberately small, but there are several useful directions for future versions:

Injectable failure selection for deterministic sequences such as “fail twice, then succeed.”
Richer synthetic responses with configurable headers and bodies, especially for Retry-After and structured error payloads.
Transport-style failure modes that complete with selected exceptions, while keeping their semantics clearly separate from HTTP responses.
More timing strategies, including progressive latency and scripted delay sequences.
Examples with common resilience libraries to show retry, circuit-breaker, and time-limiter tests end to end.

I would add these carefully. The main value of the project is that a reader can understand its behavior quickly. More features should not turn a small failure-injection wrapper into an unpredictable simulation framework.

What I learned

A few lessons stood out while building this project.

Failure paths deserve the same API fidelity as success paths. Respecting BodyHandler, cancellation, interruption, and resource ownership matters even when the response is synthetic.

Randomness is a tool, not a testing strategy by itself. Random failure is useful for exploration. Guaranteed boundary values are better for regression tests.

The layer of injection defines the failures you can claim to test. An HTTP wrapper can validate application behavior around latency and status codes. It cannot prove behavior under DNS, TLS, or connection-level faults.

Small utilities benefit from detailed documentation. The code may be compact, but users still need to understand timing, matching, lifecycle, and failure semantics.

The hardest part was not generating a 503. It was making that generated response behave enough like the real API that application tests remain meaningful.

Closing thoughts

Flaky HTTP started from a narrow question: can I make an existing Java HTTP integration fail on purpose, without changing the remote service?

The result is intentionally modest. It is a wrapper, not a platform. But it creates a useful seam for testing retries, timeouts, circuit breakers, fallbacks, caches, observability, and other behavior that is easy to design and surprisingly easy to leave unverified.

The project is available on GitHub, with the complete README, examples, Javadocs, and tests.

If you work with Java HTTP integrations, I would be interested to hear which failure modes are hardest to reproduce in your own test suites.

You can also find me at tapadyuti.com and here on DEV Community.

A Date Is Never Just a Date: From West Bengal's Panjika to a Bengali Calendar Library for Java 21

tapadyuti chatterjee — Mon, 24 Aug 2026 10:33:12 +0000

LocalDate.of(2024, 4, 14) looks innocent enough.

Ask Java what day it represents and the answer is easy. Ask what Bengali date it represents, and a more interesting question appears:

Which Bengali calendar system do you mean?

That question is exactly why I built bengali-calendar, a Java 21 library for converting between Gregorian and Bengali dates while making the selected calendar convention explicit. Version 1.0.0 provides West Bengal Traditional and Bangladesh Revised modes; the precise scope of the latter is explained below.

I am from West Bengal, India, so this subject is personal to me. Bengali dates are not an abstract alternative numbering system that I discovered while designing an API. They were already present in the panjika at home, in the arrival of Poila Boishakh, in shopkeepers' haal khata, in the six seasons, and in the familiar question many families in West Bengal ask: When is Pujo this year?

This library grew from the wish to represent part of that lived culture in Java without pretending that one Bengali calendar convention speaks for every Bengali community.

Cover illustration: AI-generated and inspired by the Patua/Patachitra tradition of West Bengal; it is not presented as artisan-made traditional work.

Version 1.0.0 is now available on Maven Central:
https://central.sonatype.com/artifact/com.tapadyuti/bengali-calendar/overview

<dependency>
    <groupId>com.tapadyuti</groupId>
    <artifactId>bengali-calendar</artifactId>
    <version>1.0.0</version>
</dependency>

This post is about what the library does and how to use it. I will not go deep into the implementation because I have not opened the source repository for contributions yet. But there is plenty to explore from the public API alone.

TL;DR

If you are already reaching for the copy button:

import com.tapadyuti.bengalicalendar.*;
import java.time.LocalDate;

BengaliDate date = BengaliCalendar.from(
    LocalDate.of(2024, 4, 14),
    BengaliCalendarSystem.WEST_BENGAL_TRADITIONAL
);

System.out.println(
    date.format("dd MMMM yyyy E", BengaliLocale.BENGALI)
);

// ০১ বৈশাখ ১৪৩১ WB

The library provides:

Gregorian to Bengali conversion
Bengali to Gregorian conversion
WEST_BENGAL_TRADITIONAL and BANGLADESH_REVISED systems, with the version-specific compatibility note below
English and Bengali-script formatting
Bengali numeral parsing
Immutable date arithmetic
Year-month and date-range helpers
Bengali seasons, weekdays, and selected holidays
java.time interoperability through ChronoLocalDate and Chronology
Java 21 and JPMS support

Maven coordinates:

com.tapadyuti:bengali-calendar:1.0.0

A calendar carries more than dates

Most of us meet calendars as grids: rows, columns, holidays, and perhaps a red circle around a deadline we are trying not to think about.

But calendars are also records of astronomy, agriculture, administration, language, and culture. The Bengali calendar is a particularly good example.

Historians do not agree on a single origin story. One historical tradition connects the Bengali era with Shashanka, ruler of Gauda in the early seventh century, and dates the beginning of the era to approximately 593–594 CE. Another influential account, recorded by Banglapedia, describes Mughal emperor Akbar promulgating a reformed calendar in 1584 and backdating it to his accession in 1556. According to that account, one practical concern was revenue collection: the Hijri calendar was lunar, while crops and harvests followed the solar year. The astronomer Fathullah Shirazi is associated with the effort to align the calendar with the agricultural cycle.

Even the month names carry traces of the sky. Banglapedia associates names such as Baishakh, Jyaistha, and Falgun with stars or constellations used in older calendrical traditions.

The story did not stop there. Calendars are living civic systems, and Bengali calendrical practice continued to evolve. Bangladesh adopted standardized civil rules following reform efforts associated with the Bangla Academy and the committee led by Muhammad Shahidullah, and revised its official civil calendar again in 2019. Many traditional panjikas used in West Bengal continue to determine month boundaries through astronomical solar transitions.

That history also shows why software should identify a calendar rule set precisely. Version 1.0.0 currently exposes these two modes:

West Bengal Traditional follows astronomical month boundaries associated with sankranti.
BANGLADESH_REVISED in version 1.0.0 follows the earlier standardized Bangladesh rules used before the 2019 revision.

Bangladesh compatibility note: The BANGLADESH_REVISED mode in version 1.0.0 should not be interpreted as the current post-2019 official Bangladesh civil calendar. Under the 2019 Bangla Academy reform reported by Prothom Alo, the first six months have 31 days, Falgun has 29 days—or 30 in a Gregorian leap year—and the remaining five months have 30 days. If your application requires current official Bangladesh civil dates, validate against an authoritative source; this version does not yet model that scheme separately.

Neither mode should be silently guessed by a programming library. The choice affects real output, particularly near month and year boundaries. So the selected rule set is part of the date's identity in this library.

BengaliDate date = BengaliCalendar.from(
    LocalDate.now(),
    BengaliCalendarSystem.WEST_BENGAL_TRADITIONAL
);

System.out.println(date.getCalendarSystem());

// WEST_BENGAL_TRADITIONAL

That explicitness is intentional.

The West Bengal thread: Bangabda as a living calendar

In West Bengal, traditional calendrical practice remains woven into everyday cultural life. It is solar in structure, and month boundaries are connected to the Sun's movement from one zodiacal region to another—the transitions known as sankranti. This astronomical lineage is commonly associated with the Surya Siddhanta, a foundational Sanskrit work on astronomy. The traditional West Bengal convention therefore cannot be represented accurately as a simple fixed offset from the Gregorian calendar.

And then there is the panjika.

Calling a panjika a “calendar” is accurate, but incomplete. It has traditionally brought together dates, tithi, nakshatra, festivals, eclipses, auspicious times, and other information people use to organize religious and social life. Printed Bengali almanacs also became part of Bengal's wider print culture. Nineteenth-century editions could carry practical information ranging from fairs and holidays to postal rates, weights, measures, agriculture, and health. The panjika was not merely something hanging on a wall; it was a compact annual guide to the world.

That legacy remains visible in how many people in West Bengal experience the year. Poila Boishakh marks the Bengali New Year, and businesses may open a fresh haal khata, traditionally beginning a new ledger and renewing relationships with customers. Celebrations vary across families and communities; common practices include exchanging Shubho Noboborsho greetings, wearing new clothes, sharing sweets and festive meals, and, for some, visiting temples.

Traditional panjikas also help many communities determine the dates of observances such as Durga Puja, Kali Puja, Saraswati Puja, Jamai Shashthi, and Bhai Phonta. Many of these depend on tithi and other lunisolar or ritual calculations. To be clear, bengali-calendar is a date-conversion library, not a complete replacement for a traditional panjika or a general-purpose tithi engine. That boundary matters just as much as the features the library does provide.

For me, the West Bengal calendar carries memories as much as dates: the turn of a season, handwritten entries in a new calendar, the anticipation before Pujo, and the familiar Bengali month name that makes a Gregorian date feel closer to home.

Meet the twelve Bengali months

The Bengali year begins with Baishakh, not January, and runs through twelve months grouped into six traditional seasons. Each pair of months gives the year a different mood—from the heat of Grishma to the rain of Barsha, the clear skies of Sharat, and the colour of Basanta.

Gregorian ranges below are deliberately approximate. Exact boundaries can shift with the year and the chosen Bengali calendar system.

No.	Bengali month	Transliteration	Season	Rough Gregorian period
১	বৈশাখ	Baishakh	গ্রীষ্ম — Grishma (summer)	April–May
২	জ্যৈষ্ঠ	Jyaistha	গ্রীষ্ম — Grishma (summer)	May–June
৩	আষাঢ়	Ashadha	বর্ষা — Barsha (monsoon)	June–July
৪	শ্রাবণ	Shraban	বর্ষা — Barsha (monsoon)	July–August
৫	ভাদ্র	Bhadra	শরৎ — Sharat (autumn)	August–September
৬	আশ্বিন	Ashwin	শরৎ — Sharat (autumn)	September–October
৭	কার্তিক	Kartik	হেমন্ত — Hemanta (late autumn)	October–November
৮	অগ্রহায়ণ	Agrahayan	হেমন্ত — Hemanta (late autumn)	November–December
৯	পৌষ	Paush	শীত — Shita (winter)	December–January
১০	মাঘ	Magh	শীত — Shita (winter)	January–February
১১	ফাল্গুন	Falgun	বসন্ত — Basanta (spring)	February–March
১২	চৈত্র	Chaitra	বসন্ত — Basanta (spring)	March–April

These names are not just labels. Baishakh opens the year with Poila Boishakh; Ashwin is inseparable in West Bengal from the anticipation of Durga Puja; Agrahayan carries the memory of the harvest; Paush evokes winter fairs and pithe-puli; Falgun arrives with spring colour; and Chaitra closes the year before the cycle begins again.

The library exposes the months in calendar order and in both scripts:

for (BengaliMonth month : BengaliMonth.values()) {
    System.out.printf(
        "%d. %s — %s%n",
        month.getValue(),
        month.getDisplayName(BengaliLocale.BENGALI),
        month.getDisplayName(BengaliLocale.ENGLISH)
    );
}

// 1. বৈশাখ — Baishakh
// 2. জ্যৈষ্ঠ — Jyaistha
// 3. আষাঢ় — Ashadha
// 4. শ্রাবণ — Shraban
// 5. ভাদ্র — Bhadra
// 6. আশ্বিন — Ashwin
// 7. কার্তিক — Kartik
// 8. অগ্রহায়ণ — Agrahayan
// 9. পৌষ — Paush
// 10. মাঘ — Magh
// 11. ফাল্গুন — Falgun
// 12. চৈত্র — Chaitra

Why West Bengal Traditional is the default

If no calendar system is supplied, the library uses:

BengaliDate today = BengaliCalendar.today();

System.out.println(today.getCalendarSystem());
// WEST_BENGAL_TRADITIONAL

I chose that default because I am from West Bengal and it is the convention closest to the context in which I experienced the Bengali calendar. It is a personal and documented default—not a claim that the West Bengal convention is more authentic, or that every Bengali application should use it.

Bengali-speaking communities in West Bengal and Bangladesh use distinct calendar conventions shaped by their own histories. Software should respect those differences by making the chosen system visible:

BengaliDate westBengalDate = BengaliCalendar.from(
    LocalDate.now(),
    BengaliCalendarSystem.WEST_BENGAL_TRADITIONAL
);

BengaliDate bangladeshDate = BengaliCalendar.from(
    LocalDate.now(),
    BengaliCalendarSystem.BANGLADESH_REVISED
);

System.out.println(westBengalDate.getCalendarSystem());
System.out.println(bangladeshDate.getCalendarSystem());

// WEST_BENGAL_TRADITIONAL
// BANGLADESH_REVISED

The default reflects where I come from. The API makes room for more than where I come from.

Installation

Maven

<dependency>
    <groupId>com.tapadyuti</groupId>
    <artifactId>bengali-calendar</artifactId>
    <version>1.0.0</version>
</dependency>

Gradle

implementation 'com.tapadyuti:bengali-calendar:1.0.0'

The library requires Java 21 or later.

If your project uses JPMS, add:

requires com.tapadyuti.bengalicalendar;

Your first conversion

The smallest useful example is a Gregorian-to-Bengali conversion:

In the examples below, lines beginning with // show the expected console output. Results based on LocalDate.now() are marked as variable.

import com.tapadyuti.bengalicalendar.BengaliCalendar;
import com.tapadyuti.bengalicalendar.BengaliCalendarSystem;
import com.tapadyuti.bengalicalendar.BengaliDate;

import java.time.LocalDate;

public class BengaliCalendarDemo {
    public static void main(String[] args) {
        LocalDate gregorian = LocalDate.of(2024, 4, 14);

        BengaliDate bengali = BengaliCalendar.from(
            gregorian,
            BengaliCalendarSystem.BANGLADESH_REVISED
        );

        System.out.println(bengali.getYear());       // 1431
        System.out.println(bengali.getMonth());      // BAISHAKH
        System.out.println(bengali.getDayOfMonth()); // 1
    }
}

The conversion is bidirectional:

LocalDate original = LocalDate.of(2024, 4, 14);

BengaliDate bengali = BengaliCalendar.from(
    original,
    BengaliCalendarSystem.BANGLADESH_REVISED
);

LocalDate convertedBack = BengaliCalendar.toGregorian(bengali);

System.out.println(convertedBack); // 2024-04-14

You can also ask for today's Bengali date:

BengaliDate today = BengaliCalendar.today();
System.out.println(
    today.format("dd MMMM yyyy E", BengaliLocale.ENGLISH)
);

// Output varies with the date; the final marker is WB by default.

The default is WEST_BENGAL_TRADITIONAL. In reusable or shared code, I still recommend specifying the system when the distinction matters:

BengaliDate westBengalToday = BengaliCalendar.today(
    BengaliCalendarSystem.WEST_BENGAL_TRADITIONAL
);

BengaliDate bangladeshToday = BengaliCalendar.today(
    BengaliCalendarSystem.BANGLADESH_REVISED
);

System.out.println(westBengalToday.getCalendarSystem());
System.out.println(bangladeshToday.getCalendarSystem());

// WEST_BENGAL_TRADITIONAL
// BANGLADESH_REVISED

One Gregorian date, two Bengali conventions

The two systems are deliberately represented by an enum:

LocalDate date = LocalDate.of(2024, 4, 14);

BengaliDate wb = BengaliCalendar.from(
    date,
    BengaliCalendarSystem.WEST_BENGAL_TRADITIONAL
);

BengaliDate bd = BengaliCalendar.from(
    date,
    BengaliCalendarSystem.BANGLADESH_REVISED
);

System.out.println(wb.getCalendarSystem()); // WEST_BENGAL_TRADITIONAL
System.out.println(bd.getCalendarSystem()); // BANGLADESH_REVISED

This is more than metadata. A BengaliDate keeps its calendar system with it, so later operations know which rules to apply:

BengaliDate nextWeek = wb.plusDays(7);

System.out.println(nextWeek.getCalendarSystem());
// WEST_BENGAL_TRADITIONAL

Configure an application-wide default

If your application consistently uses one convention, set it once during startup:

BengaliCalendar.setDefault(
    BengaliCalendarSystem.BANGLADESH_REVISED
);

BengaliDate today = BengaliCalendar.today();
BengaliDate converted = BengaliCalendar.from(LocalDate.now());

System.out.println(today.getCalendarSystem());
System.out.println(converted.getCalendarSystem());

// BANGLADESH_REVISED
// BANGLADESH_REVISED

You can read the current default too:

BengaliCalendarSystem system = BengaliCalendar.getDefault();
System.out.println(system);

// BANGLADESH_REVISED

For servers and containers, the same choice can be supplied as a JVM property:

java -Dbengalicalendar.default.system=BANGLADESH_REVISED -jar app.jar

Accepted short forms are BD and WB.

Bengali numerals: ০ থেকে ৯

Bengali has its own decimal digits. They represent exactly the same values as Western digits; only the glyphs change.

Value	Western digit	Bengali digit
Zero	0	০
One	1	১
Two	2	২
Three	3	৩
Four	4	৪
Five	5	৫
Six	6	৬
Seven	7	৭
Eight	8	৮
Nine	9	৯

So the Bengali year 1431 is written ১৪৩১, and 01 Baishakh 1431 becomes ০১ বৈশাখ ১৪৩১.

You do not need to replace the digits yourself. Selecting BengaliLocale.BENGALI makes the formatter use Bengali month names and Bengali numerals together:

BengaliDate pohelaBoishakh = BengaliDate.of(
    1431,
    BengaliMonth.BAISHAKH,
    1,
    BengaliCalendarSystem.WEST_BENGAL_TRADITIONAL
);

System.out.println(
    pohelaBoishakh.format("dd/MM/yyyy", BengaliLocale.ENGLISH)
);
System.out.println(
    pohelaBoishakh.format("dd/MM/yyyy", BengaliLocale.BENGALI)
);

// 01/01/1431
// ০১/০১/১৪৩১

The same applies in reverse: the parser can read Bengali digits directly, so users do not have to transliterate their dates before submitting them.

Formatting in English and Bengali

A cultural date library should not stop at returning an enum and an integer.

Format a Bengali date in English:

BengaliDate date = BengaliDate.of(
    1431,
    BengaliMonth.BAISHAKH,
    1,
    BengaliCalendarSystem.WEST_BENGAL_TRADITIONAL
);

String english = date.format(
    "dd MMMM yyyy E",
    BengaliLocale.ENGLISH
);

System.out.println(english);
// 01 Baishakh 1431 WB

Now format the same date in Bengali script and Bengali numerals:

String bengali = date.format(
    "dd MMMM yyyy E",
    BengaliLocale.BENGALI
);

System.out.println(bengali);
// ০১ বৈশাখ ১৪৩১ WB

The formatter supports a compact set of familiar tokens:

Token	Meaning
`d`	Day without padding
`dd`	Zero-padded day
`M`	Month number
`MM`	Zero-padded month number
`MMM`	Abbreviated month name
`MMMM`	Full month name
`y`	Bengali year
`yyyy`	Four-digit Bengali year
`E`	Calendar-system abbreviation (`BD` or `WB`)

For example:

System.out.println(date.format("d/M/y"));
System.out.println(date.format("dd-MM-yyyy E"));
System.out.println(date.format("MMMM d, yyyy", BengaliLocale.ENGLISH));

// 1/1/1431
// 01-01-1431 WB
// Baishakh 1, 1431

Parsing—including Bengali numerals

Formatting is only half the job. User input has to make the return journey.

Parse an English-numeral date:

BengaliDate parsed = BengaliDateFormatter.parse(
    "01-01-1431",
    "dd-MM-yyyy",
    BengaliCalendarSystem.BANGLADESH_REVISED,
    BengaliLocale.ENGLISH
);

System.out.println(
    parsed.format("dd MMMM yyyy E", BengaliLocale.ENGLISH)
);

// 01 Baishakh 1431 BD

Or parse Bengali numerals directly:

BengaliDate parsedBengali = BengaliDateFormatter.parse(
    "০১-০১-১৪৩১",
    "dd-MM-yyyy",
    BengaliCalendarSystem.WEST_BENGAL_TRADITIONAL,
    BengaliLocale.BENGALI
);

System.out.println(
    parsedBengali.format("dd MMMM yyyy E", BengaliLocale.BENGALI)
);

// ০১ বৈশাখ ১৪৩১ WB

Then convert the result into a regular Java date whenever you need to store, compare, or integrate it with another system:

LocalDate isoDate = parsedBengali.toGregorian();
System.out.println(isoDate);

// 2024-04-14

Date arithmetic without manual month tables

Nobody should have to write a chain of if statements just to find “ten Bengali days from now.”

BengaliDate pohelaBoishakh = BengaliDate.of(
    1431,
    BengaliMonth.BAISHAKH,
    1,
    BengaliCalendarSystem.BANGLADESH_REVISED
);

BengaliDate tenDaysLater = pohelaBoishakh.plusDays(10);
BengaliDate nextMonth = pohelaBoishakh.plusMonths(1);
BengaliDate nextYear = pohelaBoishakh.plusYears(1);

BengaliDate previousDay = pohelaBoishakh.minusDays(1);

System.out.println(tenDaysLater.format("dd MMMM yyyy E"));
System.out.println(nextMonth.format("dd MMMM yyyy E"));
System.out.println(nextYear.format("dd MMMM yyyy E"));
System.out.println(previousDay.format("dd MMMM yyyy E"));

// 11 Baishakh 1431 BD
// 01 Jyaistha 1431 BD
// 01 Baishakh 1432 BD
// 30 Chaitra 1430 BD

Comparisons are available directly:

if (tenDaysLater.isAfter(pohelaBoishakh)) {
    System.out.println("Time still works.");
}

// Time still works.

Because BengaliDate implements ChronoLocalDate, it also participates in Java's temporal APIs:

long epochDay = pohelaBoishakh.toEpochDay();
long daysBetween = pohelaBoishakh.until(tenDaysLater, java.time.temporal.ChronoUnit.DAYS);

System.out.println(epochDay);
System.out.println(daysBetween);

// 19827
// 10

Building a calendar UI

For a calendar grid, BengaliYearMonth avoids repeatedly reconstructing year and month information:

BengaliCalendar.setDefault(
    BengaliCalendarSystem.WEST_BENGAL_TRADITIONAL
);

BengaliYearMonth baishakh = BengaliYearMonth.of(
    1431,
    BengaliMonth.BAISHAKH
);

int daysInMonth = baishakh.lengthOfMonth();
BengaliDate twelfthDay = baishakh.atDay(12);

System.out.println(daysInMonth);
System.out.println(twelfthDay.format("dd MMMM yyyy E"));

// 31
// 12 Baishakh 1431 WB

For inclusive intervals, use BengaliDateRange:

BengaliDate start = BengaliDate.of(
    1431,
    BengaliMonth.BAISHAKH,
    1,
    BengaliCalendarSystem.WEST_BENGAL_TRADITIONAL
);

BengaliDate end = start.plusDays(6);
BengaliDateRange firstWeek = BengaliDateRange.of(start, end);

System.out.println(firstWeek.lengthInDays()); // 7

firstWeek.stream()
    .map(d -> d.format("dd MMMM", BengaliLocale.BENGALI))
    .forEach(System.out::println);

// ০১ বৈশাখ
// ০২ বৈশাখ
// ০৩ বৈশাখ
// ০৪ বৈশাখ
// ০৫ বৈশাখ
// ০৬ বৈশাখ
// ০৭ বৈশাখ

You can also ask whether a date belongs to a range:

boolean inside = firstWeek.contains(start.plusDays(3));
System.out.println(inside);

// true

Seasons, weekdays, and selected holidays

The Bengali year is traditionally divided into six seasons, each associated with two months. That relationship is available from a date:

BengaliSeason season = pohelaBoishakh.getSeason();

System.out.println(
    season.getDisplayName(BengaliLocale.BENGALI)
);

// গ্রীষ্ম

Weekday names are available as well:

BengaliDayOfWeek weekday = pohelaBoishakh.getDayOfWeek();

System.out.println(
    weekday.getDisplayName(BengaliLocale.BENGALI)
);

// রবিবার

And selected cultural holidays can be queried from a date:

pohelaBoishakh.getHoliday().ifPresent(holiday ->
    System.out.println(
        holiday.getDisplayName(BengaliLocale.ENGLISH)
    )
);

// Pohela Boishakh

Or collected for a Bengali year and system:

Map<BengaliDate, BengaliHoliday> holidays =
    BengaliHoliday.forYear(
        1431,
        BengaliCalendarSystem.BANGLADESH_REVISED
    );

System.out.println(holidays.size());

// 3

Holiday data should be treated as a cultural convenience, not as a replacement for an official legal or organizational holiday schedule.

Working with `java.time.Chronology`

For advanced integrations, the chronology can be resolved through Java's service-loading mechanism:

import java.time.chrono.Chronology;

Chronology bengali = Chronology.of("Bengali");

System.out.println(bengali.getId());           // Bengali
System.out.println(bengali.getCalendarType()); // bengali

Or accessed directly:

BengaliChronology chronology = BengaliChronology.INSTANCE;
System.out.println(chronology.getId());

// Bengali

Most applications will find BengaliCalendar and BengaliDate simpler. The chronology integration is there for code that already works generically with Java calendar systems.

A small testing detail that matters

“Today” is usually the enemy of deterministic tests. The library therefore accepts a Clock:

import java.time.Clock;
import java.time.Instant;
import java.time.ZoneOffset;

Clock fixedClock = Clock.fixed(
    Instant.parse("2024-04-14T00:00:00Z"),
    ZoneOffset.UTC
);

BengaliCalendar.setDefault(
    BengaliCalendarSystem.WEST_BENGAL_TRADITIONAL
);

BengaliDate predictableToday = BengaliCalendar.today(fixedClock);

System.out.println(
    predictableToday.format("dd MMMM yyyy E", BengaliLocale.ENGLISH)
);

// 01 Baishakh 1431 WB

That lets application tests stay stable regardless of when or where they run.

What this library is—and what it is not

This library is intended to provide a practical Java API for:

application-level date conversion
locale-aware display and parsing
date arithmetic
calendar UI helpers
interoperability with java.time

It does not claim that the history or practice of Bengali calendrical computation can be reduced to one universally agreed table. Traditional almanacs, astronomical conventions, civil reforms, locations, and historical periods all matter.

For production code, choose the calendar system explicitly when the distinction has business or cultural significance. For historical research, religious observance, or legal use, validate results against an authoritative source for the relevant place and period.

That is not a weakness of the subject. It is the subject.

Why I built it

The first version began with a straightforward requirement: convert a Gregorian date into a Bengali date.

The requirement did not stay straightforward for long.

Once I considered the different calendar conventions used in West Bengal and Bangladesh, along with Bengali numerals, parsing, date arithmetic, seasons, holidays, ranges, and the java.time type system, it became clear that a converter function would not be enough. I wanted an API that felt natural to a Java developer without flattening the cultural differences it represents.

The result is intentionally familiar:

BengaliDate tomorrow = BengaliCalendar.today().plusDays(1);

System.out.println(
    tomorrow.format("dd MMMM yyyy E", BengaliLocale.ENGLISH)
);

// Output varies with the date; the final marker is WB by default.

But it also keeps the important part visible:

BengaliDate current = BengaliCalendar.from(
    LocalDate.now(),
    BengaliCalendarSystem.WEST_BENGAL_TRADITIONAL
);

System.out.println(current.getCalendarSystem());

// WEST_BENGAL_TRADITIONAL

Convenience where it helps; explicitness where it matters.

I am open to collaboration

The repository is not open for public contribution yet, but I am very open to conversations and collaboration around the project.

I would especially like to hear from:

Bengali calendar and panjika experts
historians and researchers working on West Bengal's calendrical and almanac traditions
developers from Bangladesh and West Bengal with real-world date examples
Java java.time and chronology specialists
localization and Bengali-language contributors
developers building calendar, cultural, education, or archival applications

Useful collaboration could include validating edge cases, comparing authoritative date tables, expanding tests, improving transliterations, refining cultural data, or shaping a future public contribution model.

If the library is useful to you—or if you find a date that deserves a closer look—leave a comment or reach out through my Dev.to profile. I would rather improve the library through informed discussion than pretend calendars are simpler than they are.

Links

If you try it, I would love to know what you build.

Building Tab Timekeeper: A Small Chrome Extension for Making Browsing Time Visible

tapadyuti chatterjee — Wed, 19 Aug 2026 02:53:36 +0000

I built Tab Timekeeper around a small question that is surprisingly easy to lose track of while browsing:

How long have I been on this website in this tab?

Browsers make it easy to open a page, follow a link, switch tabs, and return much later. What they do not normally show is the time behind that activity. Tab Timekeeper adds that missing bit of context. Click the extension icon and its popup displays a running timer for the active tab, along with the website's favicon.

The extension is intentionally small. There is no framework, backend, account, analytics pipeline, or cross-device synchronization. It is a Manifest V3 extension built with HTML and plain JavaScript, using browser-provided storage and extension APIs.

That small scope made it a useful project for learning how the parts of a Chrome extension cooperate: the manifest, service worker, content script, popup, page context, and permissions.

Tab Timekeeper keeps the interaction simple: open the popup and see the elapsed time for the current website in this tab.

The extension is available on the Chrome Web Store, where it has also received Chrome's Featured badge.

TL;DR

Tab Timekeeper is a lightweight Chrome extension that shows how long the current website has been open in the active tab.

It uses a Manifest V3 configuration, a background service worker, a content script, and a popup written in plain HTML and JavaScript. The content script stores a start timestamp and the current origin in the page's sessionStorage. The popup queries the active tab once per second, injects a small function into that page, and reads back the elapsed time and favicon. The background service worker listens for tab activation and completed page loads, although its timestamp is written to localStorage and is separate from the sessionStorage value currently used by the popup.

The project reinforced a few useful lessons: browser storage scope is an architectural decision, extension contexts need an explicit bridge, permissions should stay narrow, and a small utility benefits from keeping its interface and implementation equally focused.

Transparency note: I used AI to help format and polish the wording of this article. The app, architecture, implementation decisions, and experiences described here are my own.

The idea behind Tab Timekeeper

Many productivity tools begin by trying to change behavior. Tab Timekeeper begins one step earlier: it makes behavior visible.

The goal was not to build a full activity tracker or a system that judges which sites are productive. I wanted a quick answer for the page already in front of me. That led to a deliberately short interaction:

Open or browse to a webpage.
Continue using it normally.
Click the extension icon.
See the elapsed time for that website in that tab.

This can be useful during a study session, while researching a topic, or simply when a short break has quietly become a long one.

The distinction between a website and a page matters here. The implementation uses window.location.origin as the identity of a site. Moving between paths on the same origin can therefore remain part of the same session, while moving to another origin starts a new one.

The extension at a glance

The repository has only a few functional files:

manifest.json
background.js
content.js
popup.html
popup.js
images/

Their responsibilities are straightforward:

manifest.json declares the extension, permissions, service worker, popup, icons, and content script.
content.js initializes per-tab website timing state in sessionStorage.
background.js responds to tab lifecycle events and injects a timestamp update.
popup.html defines the compact interface.
popup.js queries the active tab, obtains the elapsed time and favicon, and refreshes the display.

Conceptually, the active path looks like this:

Page loads
    ↓
content.js records origin + start time in sessionStorage
    ↓
User opens the extension popup
    ↓
popup.js finds the active tab
    ↓
chrome.scripting.executeScript runs a small reader in that page
    ↓
Elapsed seconds + favicon URL return to the popup
    ↓
The popup formats and refreshes the timer every second

There is no application server in this architecture. All of the work happens locally in Chrome.

Manifest V3 as the wiring diagram

manifest.json is the entry point Chrome uses to understand the extension. Tab Timekeeper declares Manifest V3 and registers background.js as its service worker:

"background": {
  "service_worker": "background.js"
}

It also declares the toolbar popup:

"action": {
  "default_popup": "popup.html"
}

The content script runs on all normal web URLs:

"content_scripts": [
  {
    "matches": ["<all_urls>"],
    "js": ["content.js"]
  }
]

The extension requests activeTab and scripting, plus host access for HTTP and HTTPS pages. Those permissions match the central operation of the app: identify the current tab and execute a small function inside it.

An earlier version declared the Chrome storage permission, but it was removed. The current implementation does not use chrome.storage; it uses the webpage's own Web Storage instead. Removing an unused permission keeps the manifest closer to the actual design and reduces what the extension asks Chrome and the user to trust.

Timing a website with `sessionStorage`

The content script begins by reading two values from the current page's sessionStorage:

const baseUrl = window.location.origin;
const storedBaseUrl = window.sessionStorage.getItem('baseUrl');

if (storedBaseUrl !== baseUrl) {
  window.sessionStorage.setItem('baseUrl', baseUrl);
  window.sessionStorage.setItem('startTime', Date.now());
}

This is the core of the timer.

sessionStorage is a good fit for the current behavior because its state is associated with a browsing context rather than a permanent extension-wide history. Each tab can maintain its own timing session. The extension stores a timestamp rather than incrementing a counter in the background, so calculating elapsed time is simply:

Math.floor((Date.now() - startTime) / 1000)

That choice avoids needing a long-running one-second timer merely to preserve state. The popup can calculate the current value whenever it needs to render it.

Using the origin as the boundary also gives the feature a clear meaning: the timer represents time on a website in a tab, not necessarily time on one exact URL.

There is a tradeoff. Web Storage belongs to the page's origin, not to the extension. That keeps the solution lightweight, but it also means this is not a centralized browsing-history model. If I wanted reports across days, aggregate totals, or durable extension-owned data, chrome.storage or another extension-owned persistence layer would be a more appropriate next step.

The popup is the live view

The popup is a small HTML document with two visible pieces: a website icon and a timer.

When its DOM is ready, popup.js asks Chrome for the active tab in the current window:

chrome.tabs.query({ active: true, currentWindow: true }, (tabs) => {
  // Read timing data from the active page.
});

For a normal webpage, it then uses chrome.scripting.executeScript to run getElapsedTimeAndFavicon in the tab. That function reads startTime from the page's sessionStorage, calculates the elapsed seconds, finds the page's favicon link, and returns both values.

The result crosses back through the callback returned by executeScript:

timerElement.textContent = formatTime(results[0].result.elapsedTime);
websiteIconElement.src = results[0].result.faviconUrl;

This is the extension's communication mechanism. It does not use chrome.runtime.sendMessage or a long-lived port. For this small request-response flow, the result of script execution is enough.

The popup repeats the query every second while it is open:

setInterval(updateTimer, 1000);
updateTimer();

Calling updateTimer() immediately is a small but important detail. Without it, the popup would initially show its placeholder and wait up to a second before displaying the real value.

The timer formatter converts raw seconds into a compact Xm YYs display. The popup also avoids trying to inject into chrome:// pages, where ordinary extensions cannot run scripts, and falls back to 0m 00s.

What the service worker does

Manifest V3 background logic runs as a service worker rather than as a permanently open background page.

Tab Timekeeper listens for two events:

chrome.tabs.onActivated, when the active tab changes.
chrome.tabs.onUpdated, when a tab finishes loading.

Both call updateStartTime, which injects a function into the selected tab and writes the current time to window.localStorage.

It also checks chrome.runtime.lastError, which matters because injection can fail on restricted pages or other contexts where Chrome does not permit the operation.

There is an implementation detail here that is easy to miss: the service worker writes localStorage.startTime, while the content script and popup use sessionStorage.startTime. These are separate stores. As the code currently stands, the visible timer is driven by the content-script/session-storage path; the local-storage timestamp written by the service worker is not read by the popup.

That does not need to be hidden in an architecture explanation. Small projects often preserve traces of an earlier design as the behavior evolves. In a future cleanup, I would either remove the unused background timestamp path or make one component the clear owner of timing state. A single source of truth would make tab activation, page loading, and same-site navigation semantics easier to define and test.

Storage scope was the main architectural choice

The most interesting decision in this extension is not the timer formatting. It is where the timestamp lives.

There are several possible models:

A popup-local counter would disappear each time the popup closed.
An in-memory service-worker counter would be unreliable because Manifest V3 workers can stop when idle.
chrome.storage would provide extension-owned persistence and make aggregation easier.
Page localStorage would persist by origin beyond a single tab session.
Page sessionStorage naturally supports a tab-oriented session.

The current implementation uses the last option for the value users see. It is a compact solution to the stated feature, and it avoids pretending that the extension is a full historical tracker.

The tradeoff is that exact behavior follows browser storage and navigation rules. That is fine for a focused utility, but it is also why the README's broader claim about displaying total time across all tabs is not something I would make for the current code. The implementation reports the active website's time in the current tab; it does not maintain a cross-tab aggregate.

A small UI with one job

The popup is only 200 pixels wide. It uses inline CSS, a centered 24-pixel timer, and a 16-pixel favicon.

The popup combines the active website's favicon with a timer that updates once per second.

That limited interface reflects the product decision: opening the extension should answer the question immediately. There are no dashboards, settings, graphs, or controls competing with the result.

Adding the favicon was a useful improvement over showing only text. It provides a quick visual association with the site without requiring the popup to parse and format a hostname.

There is still room to make this path more defensive. Some pages do not declare a link[rel~="icon"], so favicon lookup should ideally handle a missing element and use a fallback. The popup could also surface a clearer unavailable state for protected browser pages instead of displaying a zero that looks like a measurement.

Decisions and tradeoffs that shaped the project

Plain JavaScript instead of a framework

For five small source files, a UI framework and build pipeline would add more structure than value. Plain JavaScript makes the runtime behavior visible and keeps the extension easy to load unpacked during development.

Calculate from a timestamp instead of counting ticks

The extension stores a start time and derives elapsed seconds. This avoids timer drift caused by assuming that a callback will run at an exact interval, and it fits Manifest V3's event-oriented execution model.

Inject a reader instead of maintaining a message bus

The popup needs two values from one active page. Returning them from executeScript keeps communication direct. A runtime message system would become more valuable if content scripts pushed events, multiple extension views consumed the same state, or the service worker coordinated a larger model.

Keep permissions aligned with behavior

The removal of the unused storage permission is a good example of permission discipline. The current extension still needs broad host access because its feature is intended to work across ordinary HTTP and HTTPS sites, but every declared capability should have a specific reason to exist.

Accept the limits of a focused tool

Tab Timekeeper is not a surveillance-style browser analytics product. It does not collect data, require an account, or send browsing activity to a backend. The architecture supports that claim: timing is performed locally in the browser.

From a tiny utility to a Featured extension

The Chrome Web Store listing currently shows Tab Timekeeper as version 1.1 and marks it Featured. It also describes the extension as collecting no user data.

What I learned

A few lessons from Tab Timekeeper have stayed with me.

First, storage scope defines product behavior. Choosing between page storage and extension storage is not just an implementation detail; it determines whether data belongs to a tab, an origin, the browser profile, or a longer-lived history.

Second, extension code runs in multiple contexts. The service worker, popup, content script, and webpage do not share one global JavaScript environment. Data has to cross those boundaries intentionally, whether through injection results, messaging, or shared extension storage.

Third, Manifest V3 rewards event-driven design. A timestamp that can be evaluated on demand is a better foundation than assuming a background process will remain alive and increment a counter forever.

Fourth, permissions are part of the product. They affect user trust and review, not only whether an API call succeeds.

Finally, small scope makes inconsistencies easier to see. The separate local-storage and session-storage paths work differently. Keeping documentation, manifest permissions, and runtime behavior synchronized is part of maintaining even a very small extension.

What I would improve next

The next version could remain lightweight while tightening a few areas:

Consolidate timing state so the content script, service worker, and popup share one explicit source of truth.
Decide and document exact reset semantics for tab activation, reloads, and navigation within the same origin.
Add safe handling for pages without a declared favicon.
Display a clear “unavailable on this page” state for protected Chrome URLs.
Add automated tests for elapsed-time formatting and the storage/reset rules.
Update the README so every advertised feature matches the shipped implementation.
Consider chrome.storage only if durable history or cross-tab totals become a real product requirement.

The important part would be preserving the extension's current character: quick, local, and simple.

Closing thoughts

Tab Timekeeper began with a narrow idea: make the time spent on the current website visible.

Building it showed how much architecture can exist inside a tiny browser utility. The manifest defines trust and capabilities. The content script gives each page context. Web Storage determines the lifetime of the timing session. Script injection bridges the popup and active page. The service worker responds to browser events without needing to stay alive permanently.

None of those pieces is large, but their boundaries matter.

You can try Tab Timekeeper on the Chrome Web Store.

If you try it, I would love to hear whether seeing the timer changes the way you use a tab—or which improvement would make it more useful for you.

Building Mathastic Twice: One Math Puzzle Game, Two Native Architectures

tapadyuti chatterjee — Sat, 15 Aug 2026 23:29:23 +0000

I recently released Mathastic, a fast-paced math puzzle game for iOS and Android.

I’m Tapadyuti Chatterjee, a software engineer interested in distributed systems, mobile development, and practical applications of AI. You can learn more about my work on my personal website or connect with me on LinkedIn.

This is also my first post on DEV, so I wanted to go beyond a simple launch announcement. Instead, I want to share how the app works, how I structured the two native codebases, and what I learned while translating the same product into SwiftUI and Jetpack Compose.

TL;DR

Mathastic is a native iOS and Android game that turns arithmetic practice into short, replayable runs. Players choose a game mode, difficulty, and operation mix, then build streaks, complete missions, earn XP, unlock themes, and track their performance over time.

The iOS version uses SwiftUI, observable state, and UserDefaults. The Android version uses Jetpack Compose, a ViewModel with StateFlow, Hilt for dependency injection, and SharedPreferences with Gson.

Both apps share the same product rules and domain concepts, but each follows the conventions of its platform instead of forcing an identical implementation.

Transparency note: I used AI to help format and polish the wording of this article. The app, architecture, implementation decisions, and experiences described here are my own.

A quick look at Mathastic

These screens show the main game flow—from choosing a mode to playing a timed run, tracking local progress, and returning for the deterministic Daily Challenge.

Choose your run	Play under pressure

Mode selection and run configuration	Timed Sprint gameplay

Track your progress	Return for the daily challenge

Local progress and leaderboard	Deterministic Daily Challenge

The idea behind Mathastic

The original idea was simple: arithmetic practice should feel less like a worksheet and more like a game you want to replay.

A basic math quiz can ask a question, accept an answer, and display a score. That works, but it does not create much momentum. For Mathastic, I wanted each session to have a small emotional arc:

Start with approachable questions.
Build a streak.
Feel the pressure increase.
Decide when to use a hint, skip, or time bonus.
Finish with a useful summary of the run.

That led to several game modes:

Timed Sprint is the classic race against the clock.
Practice removes the timer and penalties so the player can focus on repetition.
Endless increases the pressure as the run progresses.
Daily Challenge generates a consistent challenge from the current day.

Players can focus on addition, subtraction, multiplication, division, or a mixed set. Difficulty changes more than operand size: it also affects the timer, scoring, penalties, streak bonuses, and XP.

The surrounding progression system—missions, achievements, levels, unlockable themes, score history, and operation-level accuracy—exists to give players a reason to return without getting in the way of the central activity.

Starting with a shared domain model

Although the iOS and Android projects are separate native applications, I kept their domain language deliberately similar.

Both versions have equivalents of:

GameConfiguration
MathQuestion
Score
GameResult
GameMission
MissionProgress
PlayerProfile
OperationStat
DailyChallenge

Enumerations represent the major rule choices: difficulty, operation, game mode, theme, and mission type.

This was one of the most useful architectural decisions in the project. When the product has a stable vocabulary, platform-specific code becomes easier to reason about. “Timed Sprint” should mean the same thing whether its state is stored in a Swift property wrapper or a Kotlin StateFlow.

The UI implementations can differ. The game rules should not.

The high-level architecture

Conceptually, Mathastic is divided into four layers:

UI and navigation
        ↓
Game session state
        ↓
Question, mission, and challenge generation
        ↓
Local scores, progress, and preferences

The UI renders the current state and sends player actions such as answering, requesting a hint, skipping a question, or ending a run.

The game-state layer applies the rules: scoring, streaks, timing, progression, and mission updates.

Small factory components generate questions, daily challenges, and missions.

Finally, a local score store persists completed runs and derives higher-level information such as XP, levels, achievements, best scores, and operation accuracy.

I chose a local-first design. Mathastic does not require an account or server round trip to begin a game. For this kind of app, immediate startup and offline play are more valuable than introducing a backend before it is necessary.

Question generation is more than choosing two numbers

The question factory is one of the most important pieces of the app.

It selects an operation, chooses operands based on difficulty, calculates the correct result, and creates three plausible wrong answers. Mixed mode resolves to a specific operation for every question.

A few details improve the experience:

Division questions are built from a divisor and quotient, so answers remain whole numbers.
Some addition questions hide an operand instead of always hiding the result.
Wrong options are generated near the correct answer rather than being completely random.
Endless mode can promote the effective difficulty as the run develops.
Each question records its operation so the app can calculate per-operation accuracy later.

This logic is isolated from the visual layer. A screen should not need to know how to construct a valid division problem or produce convincing distractors. It only needs a MathQuestion containing a prompt, a correct answer, and a set of options.

Deterministic daily challenges

The Daily Challenge created an interesting requirement: randomness needed to be predictable.

A normal run can generate a fresh sequence. A daily challenge should be tied to the day so that different sessions receive the same underlying challenge configuration.

Both apps derive a numeric seed from the current date. That seed determines the day’s difficulty, operation mix, theme, and question sequence.

This approach has several advantages:

It does not require a backend to publish each challenge.
The challenge remains stable during the day.
Scores can be associated with the daily seed.
The behavior is easy to reproduce while debugging.

It was a good reminder that “random” and “uncontrolled” are not the same thing. Seeded randomness preserves variety while still giving the system repeatable behavior.

The iOS implementation

The iOS app is written with SwiftUI.

A NavigationStack begins at the welcome screen and moves into the active game configuration. Shared progress is held by a ScoreStore created as a StateObject at the app level and passed through the SwiftUI environment.

The game screen uses SwiftUI state for the active session:

Current question
Score and streak
Remaining time
Hint and skip counts
Mission progress
Operation statistics
Tutorial state
Final result

Persistent player settings use @AppStorage, while completed scores are encoded and stored through UserDefaults. The score store publishes a derived snapshot containing the player profile, achievements, and operation insights.

This creates a straightforward flow: changing game state causes SwiftUI to redraw the relevant parts of the interface, while saving a completed run rebuilds the player’s longer-term progress.

For reminders, iOS uses UNUserNotificationCenter with a repeating calendar trigger. The app asks for notification permission only when the player chooses to enable the reminder, which was important to me. A reminder should be an opt-in convenience, not an automatic interruption.

The Android implementation

The Android app uses Kotlin, Jetpack Compose, Material 3, and Navigation Compose.

The main architectural difference is that the active game logic lives in a GameViewModel. The view model exposes an immutable StateFlow<GameUiState>, and Compose collects that state to render the game.

Player actions call methods on the view model:

Player action
    → ViewModel updates GameUiState
    → StateFlow emits a new value
    → Compose recomposes the UI

The timer is implemented as a coroutine job inside the view model, which makes cancellation and lifecycle handling more explicit than keeping timer behavior inside a composable.

Android also uses Hilt for dependency injection. The question factory, mission factory, daily challenge factory, and score store are provided to the components that need them. SharedPreferences and Gson provide lightweight local persistence for scores and settings.

Daily reminders require more platform plumbing on Android. The implementation uses:

AlarmManager to schedule the repeating event
A BroadcastReceiver to receive it
A notification channel on Android 8 and newer
A PendingIntent to reopen the app
Runtime notification permission handling on newer Android versions

The end result looks similar to the user, but the route to that result is distinctly Android.

SwiftUI and Compose: similar ideas, different centers of gravity

SwiftUI and Jetpack Compose feel philosophically related. Both encourage declarative interfaces where the UI is a function of state.

The differences become clearer once the app grows beyond a few screens.

On iOS, SwiftUI property wrappers make it natural to keep a moderate amount of session state close to the view. Shared progress fits neatly into an observable environment object.

On Android, the ViewModel and StateFlow combination creates a stronger separation between rendering and game logic. Compose primarily observes state and forwards events.

Neither structure is automatically better. The important question is whether state has a clear owner.

If I continued expanding the iOS version, I would likely move more of the active game-session logic into a dedicated observable model. The Android version already has that boundary because its view model owns the session.

This is one of the advantages of building the same idea twice: each platform reveals architectural improvements that can inform the other.

Native parity does not mean identical code

My goal was feature parity, not line-by-line parity.

The two apps share concepts and behavior, but the implementations use native platform tools:

Concern	iOS	Android
UI	SwiftUI	Jetpack Compose
Reactive state	SwiftUI state and `ObservableObject`	`ViewModel` and `StateFlow`
Navigation	`NavigationStack`	Navigation Compose
Preferences	`@AppStorage` and `UserDefaults`	`SharedPreferences`
Score serialization	`Codable`	Gson
Dependency management	App-level environment object and direct factories	Hilt
Timers	Foundation `Timer`	Coroutines
Reminders	User Notifications framework	AlarmManager, receiver, and notification channel
Visual language	SF Symbols and SwiftUI styling	Material icons and Material 3

Trying to hide all these differences behind a rigid cross-platform shape would have made both implementations less natural.

Instead, I treated the domain model and game behavior as the contract. Everything around that contract was allowed to follow platform conventions.

Technical decisions that paid off

A few decisions had an outsized effect on maintainability.

Keep generation logic outside the UI

Question, mission, and daily challenge generation live in dedicated factories. This keeps the screens focused on presentation and interaction.

Model difficulty as behavior

Difficulty is not just a label. Each difficulty owns values such as time limit, operand range, correct-answer points, wrong-answer penalty, streak bonus, and XP multiplier.

That makes balancing changes easier and avoids scattering conditionals throughout the app.

Save raw run data, derive progression

Each completed score stores useful facts about the run: accuracy inputs, streak, XP, completed missions, game mode, difficulty, theme, daily seed, and operation statistics.

The score store then derives the profile, achievements, unlocked themes, and analytics. This is more flexible than persisting every calculated label separately.

Keep persistence lightweight

The data currently fits comfortably in local preferences as encoded JSON. Adding a database would create migration and query infrastructure without yet providing enough value.

That choice may change if the app gains cloud sync, social leaderboards, or a much larger history. Architecture should reflect current needs while leaving room for the next likely step.

Build fairness into generated questions

Clean division answers, plausible distractors, controlled operand ranges, and reproducible daily challenges are small implementation details with a large effect on player trust.

A math game can be visually polished and still feel wrong if its question generator is careless.

What I learned

The hardest part of building the app twice was not translating Swift into Kotlin. It was preserving the same experience across two different ecosystems.

A few lessons stood out.

First, write down the game rules as data. When scoring and difficulty values are centralized, the two versions are much easier to compare.

Second, state ownership matters more than framework syntax. Declarative UI is pleasant only when it is clear which component controls the timer, score, current question, and final result.

Third, small platform features can require very different implementations. A “daily reminder” is one checkbox in the interface, but underneath it involves different permissions, scheduling systems, lifecycle rules, and APIs.

Fourth, offline-first was the right constraint for this version. Avoiding accounts and network dependencies kept the core loop fast and let me spend more time on the actual game.

Finally, parity needs a checklist. It is easy to add a scoring adjustment, mission, or tutorial improvement on one platform and forget the other. Shared terminology helps, but explicit feature and rule comparisons are even better.

What I would improve next

There are several natural directions for Mathastic:

Expand automated tests around question generation, seeded challenges, scoring, and progression
Move more iOS session logic into a dedicated game-state object
Add stronger persistence migrations as the score model evolves
Improve accessibility and adaptive layouts across more device sizes
Explore optional cloud sync or shared leaderboards
Add deeper analytics that turn weak operations into targeted practice

The key word is optional. I still want the app to open quickly and let someone solve a math problem without creating an account or waiting for a server.

Closing thoughts

Mathastic began as a small math puzzle idea, but building it natively for two platforms turned it into a useful architecture exercise.

The project taught me that a shared product does not require a shared UI framework. With a clear domain model, deterministic rules, and well-defined state ownership, two native implementations can feel like the same app while still respecting their platforms.

If you try Mathastic, I would love to hear which mode you play and where the experience could improve:

Thanks for reading my first DEV post! You can find more of my projects and writing at tapadyuti.com or connect with me on LinkedIn.

DEV Community: tapadyuti chatterjee

Making HTTP Fail on Purpose: Building a Small Chaos Library for Java - Flaky HTTP

TL;DR

The problem I wanted to solve

The basic model

Why I chose composition

Synthetic responses still need to respect BodyHandler

Synchronous and asynchronous latency are different problems

Deterministic tests and probabilistic experiments

Targeting only the dependency that matters

A subtle timeout boundary

What Flaky HTTP intentionally does not simulate

A few decisions that paid off

1. Immutable configuration

2. Validation at the boundary

3. No runtime dependencies

4. Explicit scheduler ownership

5. Honest documentation of edge cases

Installation

What I would improve next

What I learned

Closing thoughts

A Date Is Never Just a Date: From West Bengal's Panjika to a Bengali Calendar Library for Java 21

TL;DR

A calendar carries more than dates

The West Bengal thread: Bangabda as a living calendar

Meet the twelve Bengali months

Why West Bengal Traditional is the default

Installation

Maven

Gradle

Your first conversion

One Gregorian date, two Bengali conventions

Configure an application-wide default

Bengali numerals: ০ থেকে ৯

Formatting in English and Bengali

Parsing—including Bengali numerals

Date arithmetic without manual month tables

Building a calendar UI

Seasons, weekdays, and selected holidays

Working with java.time.Chronology

A small testing detail that matters

What this library is—and what it is not

Why I built it

I am open to collaboration

Links

Building Tab Timekeeper: A Small Chrome Extension for Making Browsing Time Visible

TL;DR

The idea behind Tab Timekeeper

The extension at a glance

Manifest V3 as the wiring diagram

Timing a website with sessionStorage

The popup is the live view

What the service worker does

Storage scope was the main architectural choice

A small UI with one job

Decisions and tradeoffs that shaped the project

Plain JavaScript instead of a framework

Calculate from a timestamp instead of counting ticks

Inject a reader instead of maintaining a message bus

Keep permissions aligned with behavior

Accept the limits of a focused tool

From a tiny utility to a Featured extension

What I learned

What I would improve next

Closing thoughts

Building Mathastic Twice: One Math Puzzle Game, Two Native Architectures

TL;DR

A quick look at Mathastic

The idea behind Mathastic

Starting with a shared domain model

The high-level architecture

Question generation is more than choosing two numbers

Deterministic daily challenges

The iOS implementation

The Android implementation

SwiftUI and Compose: similar ideas, different centers of gravity

Native parity does not mean identical code

Technical decisions that paid off

Keep generation logic outside the UI

Synthetic responses still need to respect `BodyHandler`

Working with `java.time.Chronology`

Timing a website with `sessionStorage`