Durable Object for handling repository view counts in git-mcp codebase.

Blog

In this article, we will review durable object for handling repository view counts in git-mcp codebase. We will look at:

What are durable objects?
durable_objects in git-mcp wrangler.json
ViewCounterDO

What are durable objects?

A Durable Object is a special kind of Cloudflare Worker which uniquely combines compute with storage. Like a Worker, a Durable Object is automatically provisioned geographically close to where it is first requested, starts up quickly when needed, and shuts down when idle. You can have millions of them around the world. However, unlike regular Workers:

Each Durable Object has a globally-unique name, which allows you to send requests to a specific object from anywhere in the world. Thus, a Durable Object can be used to coordinate between multiple clients who need to work together.
Each Durable Object has some durable storage attached. Since this storage lives together with the object, it is strongly consistent yet fast to access.

Therefore, Durable Objects enable stateful serverless applications.

Learn more about Durable objects.

durable_objects in git-mcp wrangler.json

At line 33 in git-mcp/wrangler.jsonc, you will find the following code:

 "durable_objects": {
    "bindings": [
      {
        "class_name": "MyMCP",
        "name": "MCP_OBJECT",
      },
      {
        "class_name": "ViewCounterDO",
        "name": "VIEW_COUNTER",
      },
    ],
  },

Here we are focusing on the view counter durable object defined with a classname ViewCounterDO.

ViewCounterDO

In git-mcp/src/api/utils/ViewCounterDO.ts , you will find the following code:

/**
 * Durable Object for handling repository view counts
 * This provides atomic operations to avoid race conditions when incrementing view counts
 */

export class ViewCounterDO {
  private state: DurableObjectState;
  private counts: Map<string, number> = new Map();
  private buffer: Map<string, number> = new Map();
  private bufferTimer: number | null = null;
  private initialized = false;
  private BUFFER_TIME_MS = 5000; // 5 seconds
  private isTestEnvironment = false;

  constructor(state: DurableObjectState) {
    this.state = state;
    // Check if we're in a test environment (setAlarm won't be available)
    this.isTestEnvironment = !this.state.storage.setAlarm;
    // Set up periodic alarm to ensure buffer gets flushed even with low activity
    this.setupAlarm();
  }

  /**
   * Initialize the Durable Object by loading stored data
   */
  private async initialize() {
    if (this.initialized) return;

    // Load stored counts from persistent storage
    const stored = await this.state.storage.get<Map<string, number>>("counts");
    if (stored) {
      this.counts = stored;
    }

    this.initialized = true;
  }
...

The following are the functions defined in the viewCounterDO

In git-mcp/src/index.ts, viewCounterDO is exported as shown below

export { ViewCounterDO } from "./api/utils/ViewCounterDO";

In git-mcp/worker-configuration.d.ts, at line 10, you will find the following code

/* eslint-disable */
// Generated by Wrangler by running `wrangler types` (hash: b15bdb1393c2ff62c93af283c69f3ddc)
// Runtime types generated with workerd@1.20250507.0 2025-04-26 nodejs_compat
declare namespace Cloudflare {
 interface Env {
  CACHE_KV: KVNamespace;
  GITHUB_TOKEN: string;
  GROQ_API_KEY: string;
  MCP_OBJECT: DurableObjectNamespace<import("./src/index").MyMCP>;
  VIEW_COUNTER: DurableObjectNamespace<import("./src/index").ViewCounterDO>;

About me:

Hey, my name is Ramu Narasinga. I study codebase architecture in large open-source projects.

Email: ramu.narasinga@gmail.com

Want to learn from open-source? Solve challenges inspired by open-source projects.

References:

Insights from Open Source projects

Best practices used in open-source are explained, compared among multiple projects.

Study the codebase architecture and level up your skills.