Skip to content

Latest commit

 

History

History
70 lines (49 loc) · 3.66 KB

L106-node-heath-check-library.md

File metadata and controls

70 lines (49 loc) · 3.66 KB
Raw

Node Heath Check Library 2.0

Abstract

This document proposes a new, implementation-agnostic API for the Node grpc-health-check package.

Background

The current grpc-health-check package is old (the latest release was in 2020), and its API and design negatively impacts usability in a few ways:

  • Most importantly, it directly depends on the old grpc package, and inherets all of the platform compatibility problems that contributed to that package's deprecation in 2021.
  • The package has no TypeScript type information, which has become much more important in recent years.
  • The basic functionality of indicating the serving status of a service involves referring to a protobuf enum deep in a package hierarchy (e.g. grpcHealthCheck.messages.HealthCheckResponse.ServingStatus.SERVING)
  • The package exports a Client object that requires a specific gRPC implementation to be determined in advance, and it uses protoc-generated types, which are less commonly used and can be awkward to work with.

Related Proposals:

Proposal

We will publish version 2.0 of the grpc-health-check library with the following API, defined in TypeScript:

type ServingStatus = 'UNKNOWN' | 'SERVING' | 'NOT_SERVING';
interface ServingStatusMap {
  [serviceName: string]: ServingStatus;
}

class HealthImplementation {
  constructor(statusMap: ServingStatusMap);

  /* Update the saved status for the listed service, and send the update to any
   * ongoing watch streams. */
  setStatus(serviceName: string, status: ServingStatus);

  /* Serve the information in this object on the server using the
   * grpc.health.v1.Health service */
  addToServer(server: Server);
}

// The path to the health.proto file provided in this package.
const protoPath: string

/* The service definition object for the grpc.health.v1.Health service, which
 * can be passed to makeGenericClientConstructor in either implementation to
 * create a Client for the Health service. Uses definitions generated by
 * @grpc/proto-loader. */
const service: ServiceDefinition;

Rationale

Major version bump

This change is an opportunity to make some long-needed improvements to this package, and a major version bump is unlikely to negatively affect any users. Relatively few people are currently using this library, because of the previously-mentioned platform compatibility problems with the old grpc package. In addition, by default, when installing a package, Node records the dependency with a version range restricted to the same major version, it is likely that anyone who is currently using the library would continue to use the current version after a new major version is released, unless they explicitly upgrade. On the other hand, anyone who is not currently using the library would need to take explicit action either way to start using it, so the change in major version would not make a difference to them.

Switch from protoc to @grpc/proto-loader

JavaScript generation in protoc for Node.js is no longer officially supported, and since this library was created, @grpc/proto-loader-based code generation has been added to @grpc/grpc-js and @grpc/grpc-js-xds, so for consistency, it would be better to use that in this library too.

Implementation

I (murgatroid99) will implement this as this design is reviewed.