differentialhq / differential

Typescript-first background services platform with durable functions.

Differential

Differential is an open-source application code aware service mesh (control-plane) and a set of adapters (client libraries) which connects your services together with first-class support for Typescript.

1. Differential builds on the concepts developers are already familiar with, and doesn't require you to learn a new programming model.
2. Services are collections of plain old javascript functions which can be deployed in almost any compute. Services ship their own type-safe Typescript clients.
3. The control plane takes care of routing data between the functions, and recovering from transient failures, transparently.

Why would I use it?

1. Create services out of plain old Typescript functions, and get type-safe clients for free.
2. Adopt a service-oriented architecture without changing your codebase / programming model.
3. Recover your workloads from crashes and network failures without custom code.

What does the code look like?

1. Write a service that connects to the Differential control-plane

import { Differential } from "@differentialhq/core";

// You can get a token from console.differential.dev
const d = new Differential("MY_API_SECRET");

// Write your business logic as if it were local

function sum(a: number, b: number) {
  return a + b;
}

function get(url: string) {
  // ...even functions with side effects
  return fetch(url).then((res) => res.json());
}

// Register your functions with the control-plane
const myService = d.service("my-service", {
  functions: {
    sum,
    get,
  },
});

// Start the service, and it will connect to the
// control-plane and listen for function calls from other places
myService.start();

2. Consume the service with full type safety from anywhere

import { Differential } from "@differentialhq/core";

// Import the types of the Differential service
import type { myService } from "./my-service";

// Initialize the Differential SDK with the same API secret
const d = new Differential("MY_API_SECRET");

// Create a client for the service.
// (Notice that you don't have to provide an endpoint. Clients talk to the control-plane)
const client = d.service<typeof myService>("my-service");

// call the remote functions as if they were local, with full type safety
client.sum(1, 2).then(console.log); // 3

client.get("https://api.differential.dev/live").then(console.log); // { status: "ok" }

How can I get started?

1. Build your first end-to-end Differential service in 2 minutes
2. Sign up for Differential Cloud (managed version of Differential)

More Documentation

All documentation is hosted at docs.differential.dev. Here are some quick links to get you started:

• Thinking in Differential
• How it works under the hood
• Customizing Function Call Behavior

About this repo

This is a mono-repo for almost all of the Differential codebase. It contains the following repositories:

• Control Plane The control plane is the central command & control for a differential cluster. This is fully open source and can be run on your own infrastructure. We also offer a hosted version of the control plane at www.differential.dev.
• Typescript SDK The Typescript SDK is the main way to interact with Differential. It is used to define, run and call services.
• Admin Console The admin console is a web-based UI for Differential. It is used to visualize the service registry, view logs, and more.
• CLI The CLI is a command-line interface for Differential. It is used to interact with the control plane, deploy services, and more.
• Docs The docs are the main source of information for Differential. They are hosted at /docs.

Contributing

We welcome contributions to Differential! Please see our contributing guide for more information.

differential's Issues

Add a fly deploy step circumventing tests

We need a fly deploy step as an action to "break-glass" and proceed with deployments when the pre-deploy tests fail.

Decision: Websockets and persistent connections

Differential implements a very chatty protocol. This will get to be a problem as and when we scale.

However, implementing websockets and persistent connections has it's own challenges. Whenever you say the connection is persistent, you run into the problem of the server maintaining state of that connection. And that adds extra complexity, because you can't make the same assumptions as you'd have made when the server was stateless.

For example, you can't scale down (easily) without kicking off clients. And you can't scale up (easily) and rebalance as you wish. You can implement/buy a proxy that handles these concerns for you, but that's additional complexity.

Instead, we will stick with the tried and true long polling for most of our chatty workloads with keep-alives and HTTP2 support.

We may visit going fully websockets in the future, but I've a feeling we don't need to.

Caching test fails intermittently

See the run here: https://github.com/differentialhq/differential/actions/runs/7762851286/job/21174002166?pr=102

Needs to be investigated whether this is symptomatic of a bigger issue, or a stale-read problem.

When starting a service, shut it down on a possible 401 with an exit code 1

A small critic on the license

In 2024 it's not hard to create a E2E system with Node, TS and some client-side fetch. Elysia and Hono, the newest frameworks, already support this use case. I think your monetization approach by giving the open source project a viral license is flawed, as it will just make people look the integrations you did with background queues and other extra batteries and they will do it by hand on the newer frameworks.

Handling client abort

In certain circumstances, the polling agent might close the connection before getting the request, but after the atomic UPDATE has marked the job as running. In these cases, we should try to walk back the update by listening to the abort.

Some Fastify references:

• fastify/fastify#4518
• fastify/help#577