herodotpb

package module
v0.0.0-...-7c980bb Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2026 License: Apache-2.0 Imports: 7 Imported by: 2

README

Herodot protobuf

The github.com/ory/herodot/herodotpb Go module contains the Herodot protobuf schema, generated message types, and annotation extensions. It is versioned independently of the github.com/ory/herodot/v2 runtime.

Import the Go types with:

import "github.com/ory/herodot/herodotpb"

Catalogs import ory/herodot/v1/herodot.proto and use the ory.herodot.v1 annotation namespace. Go v1 modules have no major-version suffix.

Run make gen from the repository root to regenerate the protobuf types and the runtime's code table. Run GOWORK=off go test ./... from this directory to check the protobuf module independently.

Releases

Run the Release protobuf module workflow with a stable version such as v1.0.0. It checks the module, generated code, and runtime integration, then tags the checked-out master commit as herodotpb/v1.0.0. It uses GITHUB_TOKEN with contents: write.

Release the version required by v2/go.mod before releasing the runtime. The first release is herodotpb/v1.0.0; local development resolves it through go.work until it is published.

Update the runtime dependency in a follow-up PR with GOWORK=off go get github.com/ory/herodot/herodotpb@<version> from v2, then run GOWORK=off go mod tidy. Remove the initial herodotpb replacement from go.work once v1.0.0 is published. The runtime release process updates the root module's dependency metadata when releasing herodot/v2.

Documentation

Index

Constants

This section is empty.

Variables

View Source
var (
	Code_name = map[int32]string{
		0:   "CODE_UNSPECIFIED",
		1:   "CANCELLED",
		2:   "UNKNOWN",
		3:   "INVALID_ARGUMENT",
		4:   "DEADLINE_EXCEEDED",
		5:   "NOT_FOUND",
		6:   "ALREADY_EXISTS",
		7:   "PERMISSION_DENIED",
		8:   "RESOURCE_EXHAUSTED",
		9:   "FAILED_PRECONDITION",
		10:  "ABORTED",
		11:  "OUT_OF_RANGE",
		12:  "UNIMPLEMENTED",
		13:  "INTERNAL",
		14:  "UNAVAILABLE",
		15:  "DATA_LOSS",
		16:  "UNAUTHENTICATED",
		100: "EXPIRED",
		101: "GONE",
		102: "UNSUPPORTED_MEDIA_TYPE",
		103: "UNPROCESSABLE",
		104: "PAYLOAD_TOO_LARGE",
		106: "BAD_GATEWAY",
	}
	Code_value = map[string]int32{
		"CODE_UNSPECIFIED":       0,
		"CANCELLED":              1,
		"UNKNOWN":                2,
		"INVALID_ARGUMENT":       3,
		"DEADLINE_EXCEEDED":      4,
		"NOT_FOUND":              5,
		"ALREADY_EXISTS":         6,
		"PERMISSION_DENIED":      7,
		"RESOURCE_EXHAUSTED":     8,
		"FAILED_PRECONDITION":    9,
		"ABORTED":                10,
		"OUT_OF_RANGE":           11,
		"UNIMPLEMENTED":          12,
		"INTERNAL":               13,
		"UNAVAILABLE":            14,
		"DATA_LOSS":              15,
		"UNAUTHENTICATED":        16,
		"EXPIRED":                100,
		"GONE":                   101,
		"UNSUPPORTED_MEDIA_TYPE": 102,
		"UNPROCESSABLE":          103,
		"PAYLOAD_TOO_LARGE":      104,
		"BAD_GATEWAY":            106,
	}
)

Enum value maps for Code.

View Source
var (
	// Marks an enum as an error catalog.
	//
	// optional ory.herodot.v1.CatalogOptions catalog = 50000;
	E_Catalog = &file_ory_herodot_v1_herodot_proto_extTypes[0]
)

Extension fields to descriptorpb.EnumOptions.

View Source
var (
	// Annotates a reason of an error catalog, or a value of the Code enum.
	//
	// optional ory.herodot.v1.ValueOptions value = 50000;
	E_Value = &file_ory_herodot_v1_herodot_proto_extTypes[1]
)

Extension fields to descriptorpb.EnumValueOptions.

View Source
var File_ory_herodot_v1_herodot_proto protoreflect.FileDescriptor

Functions

This section is empty.

Types

type CatalogOptions

type CatalogOptions struct {

	// The domain of all reasons in the enum, e.g. "kratos.ory.com".
	Domain string `protobuf:"bytes,1,opt,name=domain,proto3" json:"domain,omitempty"`
	// contains filtered or unexported fields
}

CatalogOptions annotate an error catalog: an enum whose values, except the zero value, are reasons. The value name is used verbatim as the reason.

enum FlowReason {
  option (ory.herodot.v1.catalog).domain = "kratos.ory.com";

  FLOW_REASON_UNSPECIFIED = 0;
  FLOW_EXPIRED = 1 [(ory.herodot.v1.value).reason = {
    code: EXPIRED
    message: "The self-service flow has expired."
    metadata_keys: ["flowId"]
  }];
}

func (*CatalogOptions) Descriptor deprecated

func (*CatalogOptions) Descriptor() ([]byte, []int)

Deprecated: Use CatalogOptions.ProtoReflect.Descriptor instead.

func (*CatalogOptions) GetDomain

func (x *CatalogOptions) GetDomain() string

func (*CatalogOptions) ProtoMessage

func (*CatalogOptions) ProtoMessage()

func (*CatalogOptions) ProtoReflect

func (x *CatalogOptions) ProtoReflect() protoreflect.Message

func (*CatalogOptions) Reset

func (x *CatalogOptions) Reset()

func (*CatalogOptions) String

func (x *CatalogOptions) String() string

type Code

type Code int32

Code classifies an error independently of the transport.

The table is closed: services can't add codes. Values are never renumbered or reused, and a mapping never changes once released.

Canonical codes are numbered as in google.rpc.Code. Refinements are numbered from 100, named by meaning (never by HTTP status), and map to exactly one canonical code and exactly one HTTP status.

const (
	Code_CODE_UNSPECIFIED Code = 0
	// Canonical codes. Values equal google.rpc.Code.
	Code_CANCELLED           Code = 1
	Code_UNKNOWN             Code = 2
	Code_INVALID_ARGUMENT    Code = 3
	Code_DEADLINE_EXCEEDED   Code = 4
	Code_NOT_FOUND           Code = 5
	Code_ALREADY_EXISTS      Code = 6
	Code_PERMISSION_DENIED   Code = 7
	Code_RESOURCE_EXHAUSTED  Code = 8
	Code_FAILED_PRECONDITION Code = 9
	Code_ABORTED             Code = 10
	Code_OUT_OF_RANGE        Code = 11
	Code_UNIMPLEMENTED       Code = 12
	Code_INTERNAL            Code = 13
	Code_UNAVAILABLE         Code = 14
	Code_DATA_LOSS           Code = 15
	Code_UNAUTHENTICATED     Code = 16
	// The resource exists but is no longer valid, e.g. an expired flow.
	Code_EXPIRED Code = 100
	// The resource existed but was removed permanently.
	Code_GONE Code = 101
	// The request body has a media type the endpoint doesn't accept.
	Code_UNSUPPORTED_MEDIA_TYPE Code = 102
	// The request is well-formed but can't be processed in the current state.
	Code_UNPROCESSABLE Code = 103
	// The request body exceeds the size limit.
	Code_PAYLOAD_TOO_LARGE Code = 104
	// An upstream service returned an invalid response.
	Code_BAD_GATEWAY Code = 106
)

func (Code) Descriptor

func (Code) Descriptor() protoreflect.EnumDescriptor

func (Code) Enum

func (x Code) Enum() *Code

func (Code) EnumDescriptor deprecated

func (Code) EnumDescriptor() ([]byte, []int)

Deprecated: Use Code.Descriptor instead.

func (Code) Number

func (x Code) Number() protoreflect.EnumNumber

func (Code) String

func (x Code) String() string

func (Code) Type

func (Code) Type() protoreflect.EnumType

type CodeInfo

type CodeInfo struct {
	Code Code `protobuf:"varint,1,opt,name=code,proto3,enum=ory.herodot.v1.Code" json:"code,omitempty"`
	// contains filtered or unexported fields
}

CodeInfo is a google.rpc.Status detail that carries a refined Code over gRPC, where the status only has room for the canonical code. It lets a receiver forward the error with the original HTTP status. Senders attach it only for refinements. HTTP responses don't need it: the canonical code and the HTTP status in the body determine the Code.

func (*CodeInfo) Descriptor deprecated

func (*CodeInfo) Descriptor() ([]byte, []int)

Deprecated: Use CodeInfo.ProtoReflect.Descriptor instead.

func (*CodeInfo) GetCode

func (x *CodeInfo) GetCode() Code

func (*CodeInfo) ProtoMessage

func (*CodeInfo) ProtoMessage()

func (*CodeInfo) ProtoReflect

func (x *CodeInfo) ProtoReflect() protoreflect.Message

func (*CodeInfo) Reset

func (x *CodeInfo) Reset()

func (*CodeInfo) String

func (x *CodeInfo) String() string

type CodeMapping

type CodeMapping struct {

	// The canonical code that gRPC and the AIP-193 "status" field use.
	Canonical code.Code `protobuf:"varint,1,opt,name=canonical,proto3,enum=google.rpc.Code" json:"canonical,omitempty"`
	// The HTTP status code.
	HttpStatus uint32 `protobuf:"varint,2,opt,name=http_status,json=httpStatus,proto3" json:"http_status,omitempty"`
	// contains filtered or unexported fields
}

CodeMapping fixes how a Code is represented on each transport.

A future transport adds a field here. It never adds per-reason configuration.

func (*CodeMapping) Descriptor deprecated

func (*CodeMapping) Descriptor() ([]byte, []int)

Deprecated: Use CodeMapping.ProtoReflect.Descriptor instead.

func (*CodeMapping) GetCanonical

func (x *CodeMapping) GetCanonical() code.Code

func (*CodeMapping) GetHttpStatus

func (x *CodeMapping) GetHttpStatus() uint32

func (*CodeMapping) ProtoMessage

func (*CodeMapping) ProtoMessage()

func (*CodeMapping) ProtoReflect

func (x *CodeMapping) ProtoReflect() protoreflect.Message

func (*CodeMapping) Reset

func (x *CodeMapping) Reset()

func (*CodeMapping) String

func (x *CodeMapping) String() string

type ErrorSpec

type ErrorSpec struct {

	// The code of the reason. Required, never CODE_UNSPECIFIED.
	Code Code `protobuf:"varint,1,opt,name=code,proto3,enum=ory.herodot.v1.Code" json:"code,omitempty"`
	// The developer-facing message, the same for every occurrence. Required.
	// One or more full English sentences on one line, each ending with a
	// period, e.g. "The self-service flow has expired. Start a new flow."
	// Values that vary go into metadata, explanations into the comment.
	Message string `protobuf:"bytes,2,opt,name=message,proto3" json:"message,omitempty"`
	// The documented ErrorInfo.metadata keys, matching [a-z][a-zA-Z0-9_-]*.
	MetadataKeys []string `protobuf:"bytes,3,rep,name=metadata_keys,json=metadataKeys,proto3" json:"metadata_keys,omitempty"`
	// contains filtered or unexported fields
}

ErrorSpec describes one reason of an error catalog.

func (*ErrorSpec) Descriptor deprecated

func (*ErrorSpec) Descriptor() ([]byte, []int)

Deprecated: Use ErrorSpec.ProtoReflect.Descriptor instead.

func (*ErrorSpec) GetCode

func (x *ErrorSpec) GetCode() Code

func (*ErrorSpec) GetMessage

func (x *ErrorSpec) GetMessage() string

func (*ErrorSpec) GetMetadataKeys

func (x *ErrorSpec) GetMetadataKeys() []string

func (*ErrorSpec) ProtoMessage

func (*ErrorSpec) ProtoMessage()

func (*ErrorSpec) ProtoReflect

func (x *ErrorSpec) ProtoReflect() protoreflect.Message

func (*ErrorSpec) Reset

func (x *ErrorSpec) Reset()

func (*ErrorSpec) String

func (x *ErrorSpec) String() string

type ValueOptions

type ValueOptions struct {

	// Set on every reason of an error catalog.
	Reason *ErrorSpec `protobuf:"bytes,1,opt,name=reason,proto3" json:"reason,omitempty"`
	// Set on every value of the Code enum, except CODE_UNSPECIFIED.
	Code *CodeMapping `protobuf:"bytes,2,opt,name=code,proto3" json:"code,omitempty"`
	// contains filtered or unexported fields
}

ValueOptions annotate an enum value.

func (*ValueOptions) Descriptor deprecated

func (*ValueOptions) Descriptor() ([]byte, []int)

Deprecated: Use ValueOptions.ProtoReflect.Descriptor instead.

func (*ValueOptions) GetCode

func (x *ValueOptions) GetCode() *CodeMapping

func (*ValueOptions) GetReason

func (x *ValueOptions) GetReason() *ErrorSpec

func (*ValueOptions) ProtoMessage

func (*ValueOptions) ProtoMessage()

func (*ValueOptions) ProtoReflect

func (x *ValueOptions) ProtoReflect() protoreflect.Message

func (*ValueOptions) Reset

func (x *ValueOptions) Reset()

func (*ValueOptions) String

func (x *ValueOptions) String() string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL