vocabulary:
  name: Twirp
  description: >-
    Vocabulary and taxonomy for the Twirp RPC framework, covering protocol
    definitions, code generation, wire protocol, and implementation concepts
    for building service-to-service APIs using Protocol Buffers.
  version: '1.0'
  created: '2026-05-03'
  modified: '2026-05-03'

domains:
  - name: Framework
    description: Core Twirp framework concepts
    terms:
      - name: Twirp
        definition: >-
          A simple RPC framework built on Protocol Buffers that generates client
          and server code from .proto service definition files for Go and other languages.
      - name: Wire Protocol
        definition: >-
          The HTTP-based communication specification used by Twirp services.
          Currently at version 7. Defines URL structure, content types, and error format.
      - name: Service
        definition: >-
          A collection of RPC methods defined in a Protobuf service block, from which
          Twirp generates server handlers and client stubs.
      - name: Method
        definition: >-
          A single RPC operation in a service definition, taking one message as input
          and returning one message as output.
      - name: protoc-gen-twirp
        definition: >-
          The Protobuf compiler plugin that generates Twirp client and server code
          from .proto files.

  - name: Protocol
    description: Twirp wire protocol concepts
    terms:
      - name: Twirp URL
        definition: >-
          The HTTP URL structure for Twirp endpoints, following the pattern:
          {Base-URL}/{Prefix}/{Package}.{Service}/{Method}.
      - name: Prefix
        definition: >-
          Optional URL segment (default /twirp) prepended to all Twirp endpoint paths.
          Can be empty or a custom value.
      - name: Package
        definition: >-
          The Protobuf package name, included in the URL to namespace services.
          Often used as an API version (e.g., example.calendar.v1).
      - name: Content-Type
        definition: >-
          HTTP header controlling message encoding: application/protobuf for binary
          Protocol Buffers encoding, application/json for JSON encoding.
      - name: Twirp Error
        definition: >-
          A structured error response returned by Twirp services containing a code
          (string error type), msg (human-readable message), and optional metadata.
      - name: Error Code
        definition: >-
          String-based error classification following a well-known set of codes
          including canceled, unknown, invalid_argument, not_found, already_exists,
          permission_denied, unauthenticated, resource_exhausted, failed_precondition,
          aborted, out_of_range, unimplemented, internal, unavailable, data_loss.

  - name: Serialization
    description: Message encoding and serialization concepts
    terms:
      - name: Protocol Buffers
        definition: >-
          Language-neutral, platform-neutral binary serialization format created by Google.
          Used as the primary IDL and encoding format for Twirp services.
      - name: JSON Encoding
        definition: >-
          Alternative message encoding in Twirp where proto messages are serialized
          as JSON. Useful for debugging and integration with non-proto clients.
      - name: Binary Encoding
        definition: >-
          Compact binary Protobuf serialization (application/protobuf) used for
          production service communication.
      - name: Proto Message
        definition: >-
          A typed data structure defined in a .proto file using the message keyword,
          serving as request and response types for RPC methods.

  - name: Go Implementation
    description: Go-specific implementation concepts
    terms:
      - name: Handler Interface
        definition: >-
          The Go interface generated by protoc-gen-twirp that server implementations
          must satisfy, with one method per RPC in the service definition.
      - name: Client Implementation
        definition: >-
          Generated Go struct that implements the service interface and makes HTTP
          requests to a remote Twirp server.
      - name: Server Constructor
        definition: >-
          Generated function that wraps a handler implementation and returns an
          http.Handler for use with the standard net/http library.
      - name: Context
        definition: >-
          Go context.Context propagated through all Twirp handler calls, used for
          cancellation, deadlines, and carrying request-scoped values.

tags:
  - RPC
  - Protocol Buffers
  - Go
  - Code Generation
  - Open Source
  - HTTP
  - Protobuf