orbit

module
Version: v1.6.4 Latest Latest
Warning

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

Go to latest
Published: May 25, 2022 License: MIT

README

GoDoc coverage license

Orbit provides a powerful, MIT-licensed networking backend to interlink services. It offers RPC like features and is primarily stateless. It aims to be light-weight and customizable.

LOGO

Current Status

This project is under heavy development. The API may change at any time.

Table of Contents

  1. Features
  2. Orbit File Syntax
    1. Service
      1. Call
      2. Stream
    2. Type
      1. Basic Type
      2. Reference Type
      3. Inline Type
    3. Enum
    4. Error
  3. Similar Projects

Features

  • RPC Calls and Streams
  • Easy API declaration using custom syntax in .orbit files
  • Code generation
  • Pluggable transport protocols
    • quic
    • yamux
    • custom
  • Pluggable codecs
    • msgpack
    • custom
  • Field validation using go-playground validator

Orbit File Syntax

This section describes the syntax of .orbit files used for code generation.

Service

Per .orbit file, you must declare exactly one service.

service {
    url: "example.com:4848"
    call sayHi { ... }
    stream messages { ... }
}
  • url
    Defines the url of the service, e.g. "127.0.0.1:4587", "examplecom/my-service:9999"
    Usage: url: 'example.com/my-service:9999'
Call

Per service, you can declare as many calls as you want.

service {
    call sayHi {
        async
        timeout: 5s
        arg: {
            name string 'required,min=1'
        }
        maxArgSize: 50KB
        ret: someType
        maxRetSize: 10MiB
    }
}
  • async (default: false)
    Each async call gets executed on a separate stream, thus, it does not block other calls.
    Usage: async
  • arg (default: none)
    The argument data sent to the service. Can either be an inline or reference type.
    Usage: arg: { ... } or arg: refType
  • maxArgSize (default: MaxArgSize from options)
    The maximum allowed size of the arg data. Must only be used in conjunction with async
    Usage: maxArgSize: <size>, where <size> is a bytefmt string
    Special value: -1 -> no limit
  • ret (default: none)
    The return data sent from the service. Can either be an inline or reference type.
    Usage: ret: { ... } or ret: refType
  • maxRetSize (default: MaxRetSize from options)
    The maximum allowed size of the ret data. Must only be used in conjunction with async
    Usage: maxRetSize: <size>, where <size> is a bytefmt string
    Special value: -1 -> no limit
  • timeout (default: CallTimeout from options)
    The maximum time a call may take to finish.
    Usage: timeout: <duration>, where <duration> is a go time duration formatted string
Stream

Per service, you can declare as many streams as you want.

service {
    stream messages {
        timeout: 5s
        arg: {
            name string 'required,min=1'
        }
        ret: someType
    }
}
  • arg (default: none)
    The argument data streamed to the service. Can either be an inline or reference type.
    Usage: arg: { ... } or arg: refType
  • maxArgSize (default: MaxArgSize from options)
    The maximum allowed size of the arg data.
    Usage: maxRetSize: <size>, where <size> is a bytefmt string
    Special value: -1 -> no limit
  • ret (default: none)
    The return data streamed from the service. Can either be an inline or reference type.
    Usage: ret: { ... } or ret: refType
  • maxRetSize (default: MaxRetSize from options)
    The maximum allowed size of the ret data.
    Usage: maxRetSize: <size>, where <size> is a bytefmt string
    Special value: -1 -> no limit
Type

Per .orbit file, you can declare as many types as you want.

type someType {
    name string 'required,min=1'
    ...
}

Each field of a type must have the following syntax: <identifier> <datatype> '<validation>'

  • identifier (mandatory)
    The name of the field, must be unique within the type.
  • datatype (mandatory)
    The data type of the field. Can either be a basic type or a reference type.
  • validation (optional)
    The validation tag of the field. Internally, the tag is validated using the go-playground validator. The syntax is identical.
Basic Type

The following basic types are available.

  • bool, byte, int, int8, int16, int32, int64, uint, uint8, uint16, uint32, uint64, float32, float64, string
  • time: Equal to go's time.Time
Reference Type

A type that has been declared using the above syntax can be referenced elsewhere by its identifier

type A {
    someField int
}

type B {
    a A
}

service {
    call test {
        arg: B
    }
}
Inline Type

Calls and Streams may define types inline. Such types receive a generated identifier of the form <Call/Stream Name><Arg/Ret>, but they can not be referenced elsewhere.

service {
    call test {
        arg: {
            name string 'required'
        }
        ret: {
            age int
        }
    }
}
Enum

Per .orbit file, you can declare as many enums as you want.

enum carBrand {
    bmw = 1
    audi = 2
    volvo = 3
    toyota = 4
    vw = 5
}

Each field of an enum must have the following syntax: <name> = <identifier>

  • name (mandatory)
    The name of the field, must be unique within the enum.
  • identifier (mandatory)
    The identifier of the field, must be an unsigned integer and unique within the enum.

An enum can be used similar to basic types.

type A {
    brand carBrand 'required'
}

service {
    call getBrand {
        ret: {
            carBrand
        }
    }
}
Error

Per .orbit file, you can declare as many errors as you want.

errors {
    myFirstError = 1
    anotherOne = 2
}

Each field of an errors block must have the following syntax: <name> = <number>

  • name (mandatory)
    The name of the error, must be unique across all error blocks.
    The go error text will contain the name of the error split up by CamelCase, e.g. error "myFirstError" is constructed as errors.New("my first error")
  • number (mandatory)
    The status code used to transmit the error over the network, must be unique across all error blocks.

Similar projects

Thanks to

  • gopherize.me for our great logo

Directories

Path Synopsis
cmd
examples
full/api
code generated by orbit
code generated by orbit
simple/hello
code generated by orbit
code generated by orbit
pkg
codec
Package codec contains sub-packages with different codecs that can be used to encode/decode any entity to/from a byte stream.
Package codec contains sub-packages with different codecs that can be used to encode/decode any entity to/from a byte stream.
codec/json
Package json offers an implementation of the codec.Codec interface for the json data format.
Package json offers an implementation of the codec.Codec interface for the json data format.
codec/msgpack
Package msgpack offers an implementation of the codec.Codec interface for the msgpack data format.
Package msgpack offers an implementation of the codec.Codec interface for the msgpack data format.
packet
Package packet provides convenience methods to read/write packets to a net.Conn.
Package packet provides convenience methods to read/write packets to a net.Conn.
internal
api
bytes
Package bytes offers convenience functions to convert bytes to and from unsigned integers, respecting a defined byte-order.
Package bytes offers convenience functions to convert bytes to and from unsigned integers, respecting a defined byte-order.
codegen/lexer
Package lexer is based on Rop Pike's talk: https://www.youtube.com/watch?v=HxaD_trXwRE
Package lexer is based on Rop Pike's talk: https://www.youtube.com/watch?v=HxaD_trXwRE
rpc
strutil
Package strutil is the common sin of every Go programmer.
Package strutil is the common sin of every Go programmer.

Jump to

Keyboard shortcuts

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