schema

package
v0.18.6 Latest Latest
Warning

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

 Go to latest Published: Apr 25, 2024 License: MIT Imports: 9 Imported by: 1

README

webrpc schema

webrpc is a design/schema driven approach to writing backend servers, with fully-generated client libraries. Write your schema, and it will generate strongly-typed bindings between your server and client. The type system is described below.

Some example webrpc schemas:

  • from the _examples/, here is a schema in RIDL or in JSON
  • ..find more in ./_examples

Type system

Core types

  • byte (aka uint8)
  • bool
  • any
  • null
Integers

  • uint8

  • uint16

  • uint32

  • uint64

  • int8

  • int16

  • int32

  • int64

Floats
  • float32
  • float64
Strings
  • string
Timestamps (date/time)

List

  • List represents a JSON array over the wire
  • form: []<type>
  • ie.
    • []string
    • []uint8
    • [][]string
    • ..

Map

  • Map represents a JSON object with 0..N properties (key:value pairs) over the wire
  • form: map<key,value>
  • ie.
    • map<string,any>
    • map<string,map<string,any>>
    • map<string,[]uint8>
    • map<int64,[]string>
    • map<string,User> - where User is a struct type defined in schema

Enum

  • enum, see examples

Struct

  • struct represents a JSON object over the wire
  • struct has 0..N fields
    • field can be optional
    • fields are by default required, unless made optional
    • fields always return default values by default, ie. default of int is 0, string is "", etc. (like in Go)
      • otherwise someone should make it optional which will have it be nullable

Documentation

Index

Constants

View Source 
const (
	TypeKind_Struct = "struct"
	TypeKind_Enum   = "enum"
)
View Source 
const (
	SCHEMA_VERSION = "v1"
)

Variables

View Source 
var CoreTypeFromString = map[string]CoreType{
	"null": T_Null,
	"any":  T_Any,
	"byte": T_Byte,
	"bool": T_Bool,

	"uint":   T_Uint,
	"uint8":  T_Uint8,
	"uint16": T_Uint16,
	"uint32": T_Uint32,
	"uint64": T_Uint64,

	"int":   T_Int,
	"int8":  T_Int8,
	"int16": T_Int16,
	"int32": T_Int32,
	"int64": T_Int64,

	"float32": T_Float32,
	"float64": T_Float64,

	"string": T_String,

	"timestamp": T_Timestamp,

	"map": T_Map,
	"[]":  T_List,
}
View Source 
var CoreTypeToString = map[CoreType]string{
	T_Null: "null",
	T_Any:  "any",
	T_Byte: "byte",
	T_Bool: "bool",

	T_Uint:   "uint",
	T_Uint8:  "uint8",
	T_Uint16: "uint16",
	T_Uint32: "uint32",
	T_Uint64: "uint64",

	T_Int:   "int",
	T_Int8:  "int8",
	T_Int16: "int16",
	T_Int32: "int32",
	T_Int64: "int64",

	T_Float32: "float32",
	T_Float64: "float64",

	T_String: "string",

	T_Timestamp: "timestamp",

	T_Map:  "map",
	T_List: "[]",
}
View Source 
var NameWhitelistRexp = regexp.MustCompile(`^[a-zA-Z]+[a-zA-Z0-9_]*$`)
View Source 
var VarIntegerCoreTypes = []CoreType{
	T_Uint, T_Uint8, T_Uint16, T_Uint32, T_Uint64, T_Int, T_Int8, T_Int16, T_Int32, T_Int64,
}
View Source 
var VarKeyCoreTypes = []CoreType{
	T_String, T_Uint, T_Uint8, T_Uint16, T_Uint32, T_Uint64, T_Int, T_Int8, T_Int16, T_Int32, T_Int64,
}

Functions

func IsValidArgName 

func IsValidArgName(s string) bool

func ParseVarTypeExpr added in v0.2.0 

func ParseVarTypeExpr(schema *WebRPCSchema, expr string, vt *VarType) error

Types

type CoreType added in v0.9.0 

type CoreType int
const (
	T_Unknown CoreType = iota

	T_Null
	T_Any
	T_Byte
	T_Bool

	T_Uint
	T_Uint8
	T_Uint16
	T_Uint32
	T_Uint64

	T_Int
	T_Int8
	T_Int16
	T_Int32
	T_Int64

	T_Float32
	T_Float64

	T_String

	T_Timestamp

	T_List
	T_Map

	T_Struct // aka, a reference to our own webrpc struct type
)

func (CoreType) MarshalJSON added in v0.9.0 

func (t CoreType) MarshalJSON() ([]byte, error)

func (CoreType) String added in v0.9.0 

func (t CoreType) String() string

func (*CoreType) UnmarshalJSON added in v0.9.0 

func (t *CoreType) UnmarshalJSON(b []byte) error

type Error added in v0.11.0 

type Error struct {
	Code       int    `json:"code"`
	Name       string `json:"name"`
	Message    string `json:"message"`
	HTTPStatus int    `json:"httpStatus"`
}

func (*Error) Parse added in v0.11.0 

func (s *Error) Parse(schema *WebRPCSchema) error

type Method 

type Method struct {
	Name     string   `json:"name"`
	Comments []string `json:"comments"`

	StreamInput  bool `json:"streamInput,omitempty"`
	StreamOutput bool `json:"streamOutput,omitempty"`
	Proxy        bool `json:"-"` // TODO: actual implementation

	Inputs  []*MethodArgument `json:"inputs"`
	Outputs []*MethodArgument `json:"outputs"`

	Service *Service `json:"-"` // denormalize/back-reference
}

func (*Method) Parse 

func (m *Method) Parse(schema *WebRPCSchema, service *Service) error

type MethodArgument 

type MethodArgument struct {
	Name     string   `json:"name"`
	Type     *VarType `json:"type"`
	Optional bool     `json:"optional"`

	InputArg  bool `json:"-"` // denormalize/back-reference
	OutputArg bool `json:"-"` // denormalize/back-reference

	TypeExtra `json:",omitempty"`
}

type Parser 

type Parser interface {
	Parse(schema *WebRPCSchema) error
}

type Reader added in v0.5.0 

type Reader struct {
	File string
	// contains filtered or unexported fields
}

func NewReader added in v0.5.0 

func NewReader(r io.Reader, path string) *Reader

func (*Reader) Read added in v0.5.0 

func (r *Reader) Read(p []byte) (n int, err error)

type Service 

type Service struct {
	Name     string    `json:"name"`
	Methods  []*Method `json:"methods"`
	Comments []string  `json:"comments"`

	Schema *WebRPCSchema `json:"-"` // denormalize/back-reference
}

func (*Service) Parse 

func (s *Service) Parse(schema *WebRPCSchema) error

type Type added in v0.9.0 

type Type struct {
	Kind      string       `json:"kind"`
	Name      string       `json:"name"`
	Type      *VarType     `json:"type,omitempty"`
	Fields    []*TypeField `json:"fields,omitempty"`
	TypeExtra `json:",omitempty"`
	Comments  []string `json:"comments,omitempty"`
}

func (*Type) Parse added in v0.9.0 

func (t *Type) Parse(schema *WebRPCSchema) error

func (*Type) RequiredFields added in v0.14.2 

func (t *Type) RequiredFields() []*TypeField

type TypeExtra added in v0.9.0 

type TypeExtra struct {
	Optional bool   `json:"optional,omitempty"` // used by structs
	Value    string `json:"value,omitempty"`    // used by enums

	// Meta store extra metadata on a field for plugins
	Meta []TypeFieldMeta `json:"meta,omitempty"`
}

type TypeField added in v0.9.0 

type TypeField struct {
	Comments []string `json:"comments,omitempty"`
	Name     string   `json:"name"`

	Type      *VarType `json:"type,omitempty"`
	TypeExtra `json:",omitempty"`
}

type TypeFieldMeta added in v0.9.0 

type TypeFieldMeta map[string]interface{}

type VarListType 

type VarListType struct {
	Elem *VarType
}

type VarMapType 

type VarMapType struct {
	Key   CoreType // see, VarMapKeyCoreTypes -- only T_String or T_XintX supported
	Value *VarType
}

type VarName 

type VarName string

func (VarName) TitleDowncase 

func (v VarName) TitleDowncase() string

TitleDowncase will downcase the first letter of a string, ie. convert a name form 'FirstName' to 'firstName'

func (VarName) TitleUpcase 

func (v VarName) TitleUpcase() string

TitleUpcase will upcase the first letter of a string, ie. convert a name form 'firstName' to 'FirstName'

type VarStructType 

type VarStructType struct {
	Name string
	Type *Type
}

type VarType 

type VarType struct {
	Expr     string   // Type, ie. map<string,map<string,uint32>> or []User
	Type     CoreType // Kind, ie. int, map or struct
	Comments []string `json:"comments,omitempty"`

	List   *VarListType
	Map    *VarMapType
	Struct *VarStructType
}

func (*VarType) MarshalJSON 

func (t *VarType) MarshalJSON() ([]byte, error)

func (*VarType) Parse 

func (t *VarType) Parse(schema *WebRPCSchema) error

func (*VarType) String 

func (t *VarType) String() string

func (*VarType) UnmarshalJSON 

func (t *VarType) UnmarshalJSON(b []byte) error

type WebRPCSchema 

type WebRPCSchema struct {
	WebrpcVersion string `json:"webrpc"`
	SchemaName    string `json:"name"`
	SchemaVersion string `json:"version"`

	Types    []*Type    `json:"types"`
	Errors   []*Error   `json:"errors"`
	Services []*Service `json:"services"`

	// Deprecated. Renamed to Types. Keep this field for now, so we can
	// error out & advise users to migrate to v0.9.0+ schema format.
	Deprecated_Messages []interface{} `json:"messages,omitempty"`
}

schema of webrpc json file, and validations

func ParseSchemaJSON added in v0.2.0 

func ParseSchemaJSON(jsondata []byte) (*WebRPCSchema, error)

func (*WebRPCSchema) GetServiceByName added in v0.3.0 

func (s *WebRPCSchema) GetServiceByName(name string) *Service

func (*WebRPCSchema) GetTypeByName added in v0.9.0 

func (s *WebRPCSchema) GetTypeByName(name string) *Type

func (*WebRPCSchema) SchemaHash added in v0.4.0 

func (s *WebRPCSchema) SchemaHash() (string, error)

func (*WebRPCSchema) ToJSON added in v0.2.0 

func (s *WebRPCSchema) ToJSON() (string, error)

func (*WebRPCSchema) Validate added in v0.5.0 

func (s *WebRPCSchema) Validate() error

Validate validates the schema through the AST, intended to be called after the json has been unmarshalled

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.