stencil

README

Stencil go client

Stencil go client package provides a store to lookup protobuf descriptors and options to keep the protobuf descriptors upto date.

It has following features

• Deserialize protobuf messages directly by specifying protobuf message name
• Serialize data by specifying protobuf message name
• Ability to refresh protobuf descriptors in specified intervals
• Support to download descriptors from multiple urls

Requirements

• go 1.16

Installation

Use go get

go get github.com/goto/stencil/clients/go

Then import the stencil package into your own code as mentioned below

import stencil "github.com/goto/stencil/clients/go"

Usage

Creating a client

import stencil "github.com/goto/stencil/clients/go"

url := "http://localhost:8000/v1beta1/namespaces/{test-namespace}/schemas/{schema-name}"
client, err := stencil.NewClient([]string{url}, stencil.Options{})

Get Descriptor

import stencil "github.com/goto/stencil/clients/go"

url := "http://localhost:8000/v1beta1/namespaces/{test-namespace}/schemas/{schema-name}"
client, err := stencil.NewClient([]string{url}, stencil.Options{})
if err != nil {
    return
}
desc, err := client.GetDescriptor("google.protobuf.DescriptorProto")

Parse protobuf message.

import stencil "github.com/goto/stencil/clients/go"

url := "http://localhost:8000/v1beta1/namespaces/{test-namespace}/schemas/{schema-name}"
client, err := stencil.NewClient([]string{url}, stencil.Options{})
if err != nil {
    return
}
data := []byte("")
parsedMsg, err := client.Parse("google.protobuf.DescriptorProto", data)

Serialize data.

import stencil "github.com/goto/stencil/clients/go"

url := "http://url/to/proto/descriptorset/file"
client, err := stencil.NewClient([]string{url}, stencil.Options{})
if err != nil {
    return
}
data := map[string]interface{}{}
serializedMsg, err := client.Serialize("google.protobuf.DescriptorProto", data)

Enable auto refresh of schemas

import stencil "github.com/goto/stencil/clients/go"

url := "http://localhost:8000/v1beta1/namespaces/{test-namespace}/schemas/{schema-name}"
// Configured to refresh schema every 12 hours
client, err := stencil.NewClient([]string{url}, stencil.Options{AutoRefresh: true, RefreshInterval: time.Hours * 12})
if err != nil {
    return
}
desc, err := client.GetDescriptor("google.protobuf.DescriptorProto")

Using VersionBasedRefresh strategy

import stencil "github.com/goto/stencil/clients/go"

url := "http://localhost:8000/v1beta1/namespaces/{test-namespace}/schemas/{schema-name}"
// Configured to refresh schema every 12 hours
client, err := stencil.NewClient([]string{url}, stencil.Options{AutoRefresh: true, RefreshInterval: time.Hours * 12, RefreshStrategy: stencil.VersionBasedRefresh})
if err != nil {
    return
}
desc, err := client.GetDescriptor("google.protobuf.DescriptorProto")

Refer to go documentation for all available methods and options.

Documentation

Overview

Package stencil helps to download and refresh protobuf descriptors from remote server and provides helper functions to get protobuf schema descriptors and can parse the messages dynamically.

Index

• Variables
• type Client
  • func NewClient(urls []string, options Options) (Client, error)
• type HTTPOptions
• type Logger
• type Options
• type RefreshStrategy
• type Resolver
  • func NewResolver(data []byte) (*Resolver, error)
  • func (r *Resolver) Get(className string) (protoreflect.MessageType, bool)
  • func (r *Resolver) GetTypeResolver() *protoregistry.Types

Variables

var (
	//ErrNotFound default sentinel error if proto not found
	ErrNotFound = errors.New("not found")
	//ErrInvalidDescriptor is for when descriptor does not match the message
	ErrInvalidDescriptor = errors.New("invalid descriptor")
)

Types

type Client

type Client interface {
	// Parse parses protobuf message from wire format to protoreflect.ProtoMessage given fully qualified name of proto message.
	// Returns ErrNotFound error if given class name is not found
	Parse(string, []byte) (protoreflect.ProtoMessage, error)
	// Serialize serializes data to bytes given fully qualified name of proto message.
	// Returns ErrNotFound error if given class name is not found
	Serialize(string, interface{}) ([]byte, error)
	// GetDescriptor returns protoreflect.MessageDescriptor given fully qualified proto java class name
	GetDescriptor(string) (protoreflect.MessageDescriptor, error)
	// Close stops background refresh if configured.
	Close()
	// Refresh loads new values from specified url. If the schema is already fetched, the previous value
	// will continue to be used by Parse methods while the new value is loading.
	// If schemas not loaded, then this function will block until the value is loaded.
	Refresh()
}

Client provides utility functions to parse protobuf messages at runtime. protobuf messages can be identified by specifying fully qualified generated proto java class name.

func NewClient

func NewClient(urls []string, options Options) (Client, error)

NewClient creates stencil client. Downloads proto descriptor file from given url and stores the definitions. It will throw error if download fails or downloaded file is not fully contained descriptor file

type HTTPOptions

type HTTPOptions struct {
	// Timeout specifies a time limit for requests made by this client. Default to 10s.
	// `0` duration not allowed. Client will set to default value (i.e. 10s).
	Timeout time.Duration
	// Headers provide extra headers to be added in requests made by this client
	Headers map[string]string
}

HTTPOptions options for http client

type Logger

type Logger interface {
	Info(string)
	Error(string)
}

Logger interface used to get logging from stencil internals.

type Options

type Options struct {
	// AutoRefresh boolean to enable or disable autorefresh. Default to false
	AutoRefresh bool
	// RefreshInterval refresh interval to fetch descriptor file from server. Default to 12h.
	// `0` duration not allowed. Client will set to default value (i.e. 12h).
	RefreshInterval time.Duration
	// HTTPOptions options for http client
	HTTPOptions
	// RefreshStrategy refresh strategy to use while fetching schema.
	// Default strategy set to `stencil.LongPollingRefresh` strategy
	RefreshStrategy
	// Logger is the interface used to get logging from stencil internals.
	Logger
}

Options options for stencil client

type RefreshStrategy

type RefreshStrategy int

RefreshStrategy clients can configure which refresh strategy to use to download latest schema. Default is LongPollingRefresh strategy

const (
	// LongPollingRefresh this refresh strategy tries to update schema on every specified interval.
	// It doesn't check for schema changes explicitly.
	LongPollingRefresh RefreshStrategy = iota
	// VersionBasedRefresh this refresh strategy utilizes versions API provided by Stencil Server.
	// If new version is available then only schema cache would be updated.
	VersionBasedRefresh
)

type Resolver

type Resolver struct {
	// contains filtered or unexported fields
}

Resolver protobuf type resolver

func NewResolver

func NewResolver(data []byte) (*Resolver, error)

NewResolver parses protobuf fileDescriptorSet schema returns type Resolver

func (*Resolver) Get

func (r *Resolver) Get(className string) (protoreflect.MessageType, bool)

Get returns protobuf messageType for given proto message fullname. If java package file option is added, then message classname would be javapackage + message name. If java package file option is not defined then className would be proto message fullName.

func (*Resolver) GetTypeResolver

func (r *Resolver) GetTypeResolver() *protoregistry.Types

GetTypeResolver returns type resolver