@typespec/protobuf 0.43.0

package/src/lib.ts

@@ -0,0 +1,161 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import { createTypeSpecLibrary, JSONSchemaType, paramMessage } from "@typespec/compiler";
+
+/**
+ * Options that the Protobuf emitter accepts.
+ */
+export interface ProtobufEmitterOptions {
+  /**
+   * Don't emit anything.
+   */
+  noEmit?: boolean;
+}
+
+const EmitterOptionsSchema: JSONSchemaType<ProtobufEmitterOptions> = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    noEmit: { type: "boolean", nullable: true },
+  },
+  required: [],
+};
+
+const PACKAGE_NAME = "@typespec/protobuf";
+
+export const TypeSpecProtobufLibrary = createTypeSpecLibrary({
+  name: PACKAGE_NAME,
+  requireImports: [PACKAGE_NAME],
+  diagnostics: {
+    "field-index": {
+      severity: "error",
+      messages: {
+        missing: paramMessage`field ${"name"} does not have a field index, but one is required (try using the '@field' decorator)`,
+        invalid: paramMessage`field index ${"index"} is invalid (must be an integer greater than zero)`,
+        "out-of-bounds": paramMessage`field index ${"index"} is out of bounds (must be less than ${"max"})`,
+        reserved: paramMessage`field index ${"index"} falls within the implementation-reserved range of 19000-19999 inclusive`,
+        "user-reserved": paramMessage`field index ${"index"} was reserved by a call to @reserve on this model`,
+        "user-reserved-range": paramMessage`field index ${"index"} falls within a range reserved by a call to @reserve on this model`,
+      },
+    },
+    "field-name": {
+      severity: "error",
+      messages: {
+        "user-reserved": paramMessage`field name '${"name"}' was reserved by a call to @reserve on this model`,
+      },
+    },
+    "root-operation": {
+      severity: "error",
+      messages: {
+        default:
+          "operations in the root namespace are not supported (no associated Protobuf service)",
+      },
+    },
+    "unsupported-intrinsic": {
+      severity: "error",
+      messages: {
+        default: paramMessage`intrinsic type ${"name"} is not supported in Protobuf`,
+      },
+    },
+    "unsupported-return-type": {
+      severity: "error",
+      messages: {
+        default: "Protobuf methods must return a named Model",
+      },
+    },
+    "unsupported-input-type": {
+      severity: "error",
+      messages: {
+        "wrong-number":
+          "Protobuf methods must accept exactly one Model input (an empty model will do)",
+        "wrong-type": "Protobuf methods may only accept a named Model as an input",
+        unconvertible: "input parameters cannot be converted to a Protobuf message",
+      },
+    },
+    "unsupported-field-type": {
+      severity: "error",
+      messages: {
+        unconvertible: paramMessage`cannot convert a ${"type"} to a protobuf type (only intrinsic types and models are supported)`,
+        "unknown-intrinsic": paramMessage`no known protobuf scalar for intrinsic type ${"name"}`,
+        "unknown-scalar": paramMessage`no known protobuf scalar for TypeSpec scalar type ${"name"}`,
+        "recursive-map": "a protobuf map's 'value' type may not refer to another map",
+        union: "a message field's type may not be a union",
+      },
+    },
+    "namespace-collision": {
+      severity: "error",
+      messages: {
+        default: paramMessage`the package name ${"name"} has already been used`,
+      },
+    },
+    "unconvertible-enum": {
+      severity: "error",
+      messages: {
+        default:
+          "enums must explicitly assign exactly one integer to each member to be used in a Protobuf message",
+        "no-zero-first":
+          "the first variant of an enum must be set to zero to be used in a Protobuf message",
+      },
+    },
+    "nested-array": {
+      severity: "error",
+      messages: {
+        default: "nested arrays are not supported by the Protobuf emitter",
+      },
+    },
+    "invalid-package-name": {
+      severity: "error",
+      messages: {
+        default: paramMessage`${"name"} is not a valid package name (must consist of letters and numbers separated by ".")`,
+      },
+    },
+    "illegal-reservation": {
+      severity: "error",
+      messages: {
+        default:
+          "reservation value must be a string literal, uint32 literal, or a tuple of two uint32 literals denoting a range",
+      },
+    },
+    "model-not-in-package": {
+      severity: "error",
+      messages: {
+        default: paramMessage`model ${"name"} is not in a namespace that uses the '@Protobuf.package' decorator`,
+      },
+    },
+    "anonymous-model": {
+      severity: "error",
+      messages: {
+        default: "anonymous models cannot be used in Protobuf messages",
+      },
+    },
+    package: {
+      severity: "error",
+      messages: {
+        "disallowed-option-type": paramMessage`option '${"name"}' with type '${"type"}' is not allowed in a package declaration (only string, boolean, and numeric types are allowed)`,
+      },
+    },
+  },
+  emitter: { options: EmitterOptionsSchema },
+});
+
+export const { reportDiagnostic } = TypeSpecProtobufLibrary;
+
+export type TypeSpecProtobufLibrary = typeof TypeSpecProtobufLibrary;
+
+const keys = [
+  "fieldIndex",
+  "package",
+  "service",
+  "externRef",
+  "stream",
+  "reserve",
+  "message",
+  "_map",
+] as const;
+
+export const state = Object.fromEntries(
+  keys.map((k) => [k, TypeSpecProtobufLibrary.createStateSymbol(k)])
+) as {
+  [K in (typeof keys)[number]]: symbol;
+};

package/src/proto.ts

@@ -0,0 +1,217 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import {
+  DecoratorContext,
+  EmitContext,
+  EmitOptionsFor,
+  EnumMember,
+  Interface,
+  Model,
+  ModelProperty,
+  Namespace,
+  NumericLiteral,
+  Operation,
+  Program,
+  resolvePath,
+  Tuple,
+  Type,
+} from "@typespec/compiler";
+
+import { StreamingMode } from "./ast.js";
+import { ProtobufEmitterOptions, reportDiagnostic, state, TypeSpecProtobufLibrary } from "./lib.js";
+import { createProtobufEmitter } from "./transform/index.js";
+
+/**
+ * # @typespec/protobuf : Protobuf/gRPC Emitter and Decorators for TypeSpec
+ *
+ * This module defines an emitter and decorator library for TypeSpec that enables specifying Protobuf services and models.
+ */
+
+/**
+ * The maximum field index allowed by Protocol Buffers.
+ */
+const MAX_FIELD_INDEX = 2 ** 29 - 1;
+
+/**
+ * The field range between 19000 and 19999 is reserved for Protobuf client implementations.
+ */
+const IMPLEMENTATION_RESERVED_RANGE = [19000, 19999] as const;
+
+/**
+ * Defined in the [ProtoBuf Language Spec](https://developers.google.com/protocol-buffers/docs/reference/proto3-spec#identifiers).
+ *
+ * ident = letter \{ letter | decimalDigit | "_" \}
+ * fullIdent = ident \{ "." ident \}
+ */
+export const PROTO_FULL_IDENT = /([a-zA-Z][a-zA-Z0-9_]*)+/;
+
+/**
+ * Decorate an interface as a service, indicating that it represents a Protobuf `service` declaration.
+ *
+ * @param ctx - decorator context
+ * @param target - the decorated interface
+ */
+export function $service(ctx: DecoratorContext, target: Interface) {
+  ctx.program.stateSet(state.service).add(target);
+}
+
+export interface PackageDetails {
+  name?: string;
+}
+
+/**
+ * Declare a Protobuf package.
+ *
+ * @param ctx - decorator context
+ * @param target - target decorator namespace
+ */
+export function $package(ctx: DecoratorContext, target: Namespace, details?: Model) {
+  ctx.program.stateMap(state.package).set(target, details);
+}
+
+/**
+ * Determines whether a type represents a Protobuf map.
+ *
+ * @param program - the program context
+ * @param m - the type to test
+ * @returns true if the internal representation of a Protobuf map is bound to this type.
+ */
+export function isMap(program: Program, m: Type): boolean {
+  return program.stateSet(state._map).has(m);
+}
+
+/**
+ * Binds the internal representation of a Protobuf map.
+ * @internal
+ * @param ctx
+ * @param target
+ */
+export function $_map(ctx: DecoratorContext, target: Model) {
+  ctx.program.stateSet(state._map).add(target);
+}
+
+export function $externRef(ctx: DecoratorContext, target: Model, path: string, name: string) {
+  ctx.program.stateMap(state.externRef).set(target, [path, name]);
+}
+
+export function $stream(ctx: DecoratorContext, target: Operation, mode: EnumMember) {
+  const emitStreamingMode = {
+    Duplex: StreamingMode.Duplex,
+    In: StreamingMode.In,
+    Out: StreamingMode.Out,
+    None: StreamingMode.None,
+  }[mode.name as string];
+
+  ctx.program.stateMap(state.stream).set(target, emitStreamingMode);
+}
+
+function getTuple(program: Program, t: Type): [number, number] | null {
+  if (t.kind !== "Tuple" || t.values.some((v) => v.kind !== "Number") || t.values.length !== 2) {
+    reportDiagnostic(program, {
+      code: "illegal-reservation",
+      target: t,
+    });
+
+    return null;
+  }
+
+  return Object.assign(
+    (t as Tuple).values.map((v) => (v as NumericLiteral).value) as [number, number],
+    { type: t }
+  );
+}
+
+export type Reservation = string | number | ([number, number] & { type: Type });
+
+export function $reserve(
+  ctx: DecoratorContext,
+  target: Model,
+  ...reservations: readonly (Type | number | string)[]
+) {
+  const finalReservations = reservations
+    .map((reservation) =>
+      typeof reservation === "object" ? getTuple(ctx.program, reservation) : reservation
+    )
+    .filter((v) => v != null);
+
+  ctx.program.stateMap(state.reserve).set(target, finalReservations);
+}
+
+export function $message(ctx: DecoratorContext, target: Model) {
+  ctx.program.stateSet(state.message).add(target);
+}
+
+/**
+ * Decorate a model property with a field index. Field indices are required for all fields of emitted messages.
+ *
+ * @param param0
+ * @param target
+ * @param fieldIndex
+ * @returns
+ */
+export function $field(ctx: DecoratorContext, target: ModelProperty, fieldIndex: number) {
+  if (!Number.isInteger(fieldIndex) || fieldIndex <= 0) {
+    reportDiagnostic(ctx.program, {
+      code: "field-index",
+      messageId: "invalid",
+      format: {
+        index: String(fieldIndex),
+      },
+      target,
+    });
+    return;
+  } else if (fieldIndex > MAX_FIELD_INDEX) {
+    reportDiagnostic(ctx.program, {
+      code: "field-index",
+      messageId: "out-of-bounds",
+      format: {
+        index: String(fieldIndex),
+        max: String(MAX_FIELD_INDEX + 1),
+      },
+      target,
+    });
+    return;
+  } else if (
+    fieldIndex >= IMPLEMENTATION_RESERVED_RANGE[0] &&
+    fieldIndex <= IMPLEMENTATION_RESERVED_RANGE[1]
+  ) {
+    reportDiagnostic(ctx.program, {
+      code: "field-index",
+      messageId: "reserved",
+      format: {
+        index: String(fieldIndex),
+      },
+      target,
+    });
+  }
+
+  ctx.program.stateMap(state.fieldIndex).set(target, fieldIndex);
+}
+
+/**
+ * Emitter main function.
+ *
+ * @param program - the program to emit
+ */
+export async function $onEmit(ctx: EmitContext<EmitOptionsFor<TypeSpecProtobufLibrary>>) {
+  const emitter = createProtobufEmitter(ctx.program);
+
+  await emitter(resolvePath(ctx.emitterOutputDir), ctx.options);
+}
+
+/**
+ * Validation function
+ */
+export async function $onValidate(program: Program) {
+  // Is this correct? See https://github.com/microsoft/typespec/issues/1859
+  /* c8 ignore next 6 */
+  if (program.compilerOptions.noEmit) {
+    const options = program.emitters.find((e) => e.emitFunction === $onEmit)
+      ?.options as ProtobufEmitterOptions;
+    const emitter = createProtobufEmitter(program);
+    await emitter("", options);
+  }
+}
+
+export const namespace = "TypeSpec.Protobuf";