explaingit

nytimes/gizmo

★ 3,774GoAudience · ops devopsComplexity · 4/5LicenseSetup · hard

TLDR

A collection of Go packages from The New York Times for building HTTP servers, gRPC services, and message queue systems. In maintenance mode since April 2021, still gets critical fixes but no new features.

Mindmap

mindmap
  root((Gizmo))
    Servers
      SimpleServer HTTP
      server/kit gRPC
    Messaging
      AWS SNS/SQS
      Google Cloud PubSub
      Kafka
    Utilities
      Config loading
      Auth tokens
      Observability
    Status
      Maintenance mode
      Critical fixes only
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Things people build with this

USE CASE 1

Bootstrap a Go HTTP or gRPC microservice with built-in Google Cloud monitoring using the server/kit package

USE CASE 2

Write pub/sub code that works unchanged across AWS SQS, Google Cloud Pub/Sub, or Kafka

USE CASE 3

Load service configuration from JSON files or environment variables using the config package

USE CASE 4

Test message queue consumers locally without real cloud credentials using the mock testing package

Tech stack

GogRPCGoogle CloudAWSKafka

Getting it running

Difficulty · hard Time to first run · 1h+

Primarily designed for Google Cloud infrastructure, cloud-specific packages require GCP or AWS credentials.

Open source under a permissive license, free to use and modify in commercial and personal projects.

In plain English

Gizmo is a collection of Go packages that The New York Times built internally to make it faster to write the kind of background services their engineering teams run: HTTP servers, gRPC services, and systems that send or receive messages through queues. As of April 2021, the project is in maintenance mode, meaning it still receives fixes for critical issues but is not being developed further. The core of the toolkit is the server package, which handles HTTP and JSON request routing through a set of ready-made server types. A simpler wrapper called SimpleServer covers most common cases. A second server package called server/kit takes a more opinionated approach: it combines a popular Go server-building library called go-kit with gRPC (a way to make fast remote calls between services), and automatically connects to Google Cloud monitoring tools when the service is running on Google infrastructure or Amazon EC2. For services that need to pass messages between components, Gizmo provides a pubsub layer. This gives developers a consistent way to publish and subscribe to messages regardless of the underlying system. The same code structure works whether the team is using Amazon SNS/SQS, Google Cloud Pub/Sub, or Kafka. There is also a testing package that lets developers simulate these message queues locally without needing real cloud credentials. The toolkit also includes packages for configuration loading (reading settings from JSON files or environment variables), authentication token verification, and observability helpers. The authentication packages include GCP-specific helpers for verifying the identities of services running inside Google Cloud, with support for both identity tokens and IAM-based signing. Because this toolkit was built for New York Times production infrastructure, it reflects choices suited to that environment, especially around Google Cloud. Teams working primarily outside GCP may find some packages more useful than others. The examples directory in the repository shows how the server and pubsub pieces fit together in practice.

Copy-paste prompts

Prompt 1
Using Gizmo SimpleServer, write a Go HTTP service with a JSON health check endpoint.
Prompt 2
How do I use Gizmo's pubsub package to publish a message to Google Cloud Pub/Sub and subscribe to messages in the same service?
Prompt 3
Write a Go service using Gizmo server/kit that automatically registers with Google Cloud monitoring when deployed on GCP.
Prompt 4
Show me how to use Gizmo's config package to load settings from environment variables into a typed Go struct.
Open on GitHub → Explain another repo

← nytimes on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.