api

package
Version: v0.1.1 Latest Latest
Warning

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

Go to latest
Published: May 20, 2016 License: Apache-2.0 Imports: 13 Imported by: 24

README

Lever OS

Go library for Lever OS

The Go library can be used for both implementing Lever services in Go and invoking Lever methods, as a client.

GoDoc ReadMe.io Build Status License Analytics

Documentation

See Godoc.

Installation

go get -u github.com/leveros/leveros/api
import leverapi "github.com/leveros/leveros/api"

Quick example

Server
$ mkdir hello
$ cd hello
server.go
package main

import (
	"fmt"
	"log"

	leverapi "github.com/leveros/leveros/api"
)

func main() {
	server, err := leverapi.NewServer()
	if err != nil {
		log.Fatalf("Error: %v\n", err)
	}
	err = server.RegisterHandlerObject(new(Handler))
	if err != nil {
		log.Fatalf("Error: %v\n", err)
	}
	server.Serve()
}

type Handler struct {
}

func (*Handler) SayHello(name string) (result string, err error) {
	return fmt.Sprintf("Hello, %s!", name), nil
}
lever.json
{
    "name": "helloService",
    "description": "A hello service.",
    "entry": ["./serve"]
}

Compile and deploy

$ GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -o ./serve server.go
$ lever deploy

Note the env vars for compiling for Lever OS. These need to be GOOS=linux GOARCH=amd64 CGO_ENABLED=0 even when running on Mac or Windows.

If you have problems building, you may need to reinstall Go to include cross-compilation support. On a Mac, you can achieve this with brew install go --with-cc-common.

To try it out, invoke it with the CLI:

$ lever invoke /helloService/SayHello '"world"'

"Hello, world!"
Client
client.go
package main

import (
	"log"
	"os"

	leverapi "github.com/leveros/leveros/api"
)

func main() {
    client, err := leverapi.NewClient()
    if err != nil {
		log.Fatalf("Error: %v\n", err)
	}
	client.ForceHost = os.Getenv("LEVEROS_IP_PORT")
    leverService := client.Service("dev.lever", "helloService")
    var reply string
    err = leverService.Invoke(&reply, "SayHello", "world")
    if err != nil {
        log.Printf("Error: %v\n", err)
    }
    log.Printf("%s\n", reply) // Hello, world!
}

Run

# Without docker-machine
$ LEVEROS_IP_PORT="127.0.0.1:8080" go run client.go

# With docher-machine
$ LEVEROS_IP_PORT="$(docker-machine ip default):8080" go run client.go

Setting LEVEROS_IP_PORT is necessary so that you can invoke the dev.lever environment without adding an entry for it in /etc/hosts and setting the listen port to 80.

Documentation

Overview

Package api provides Lever OS libraries for both implementing Lever services in Go and invoking Lever methods, as a client.

Quick example of a Lever service implementation

$ mkdir hello
$ cd hello

server.go

package main

import (
    "fmt"
    "log"

    leverapi "github.com/leveros/leveros/api"
)

func main() {
	server, err := leverapi.NewServer()
	if err != nil {
		log.Fatalf("Error: %v\n", err)
	}
	err = server.RegisterHandlerObject(new(Handler))
	if err != nil {
		log.Fatalf("Error: %v\n", err)
	}
	server.Serve()
}

type Handler struct {
}

func (*Handler) SayHello(name string) (result string, err error) {
	return fmt.Sprintf("Hello, %s!", name), nil
}

lever.json

{
    "name": "helloService",
    "description": "A hello service.",
    "entry": ["./serve"]
}

Compile and deploy

$ GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -o ./serve server.go
$ lever deploy

Note the env vars for compiling for Lever OS. These need to be GOOS=linux GOARCH=amd64 CGO_ENABLED=0 even when running on Mac or Windows.

If you have problems building, you may need to reinstall Go to include cross-compilation support. On a Mac, you can achieve this with brew install go --with-cc-common.

To try it out, invoke it with the CLI:

$ lever invoke /helloService/SayHello '"world"'

"Hello, world!"

Quick example of a Lever client

package main

import (
	"log"
	"os"

	leverapi "github.com/leveros/leveros/api"
)

func main() {
    client, err := leverapi.NewClient()
    if err != nil {
		log.Fatalf("Error: %v\n", err)
	}
	client.ForceHost = os.Getenv("LEVEROS_IP_PORT")
    leverService := client.Service("dev.lever", "helloService")
    var reply string
    err = leverService.Invoke(&reply, "SayHello", "world")
    if err != nil {
        log.Printf("Error: %v\n", err)
    }
    log.Printf("%s\n", reply) // Hello, world!
}

To run this

# Without docker-machine
$ LEVEROS_IP_PORT="127.0.0.1:8080" go run client.go

# With docher-machine
$ LEVEROS_IP_PORT="$(docker-machine ip default):8080" go run client.go

Setting LEVEROS_IP_PORT is necessary so that you can invoke the dev.lever environment without adding an entry for it in /etc/hosts and setting the listen port to 80.

Index

Constants

View Source
const PackageName = "api"

PackageName is the name of this package.

Variables

View Source
var (
	// OwnEnvironment is the name of the environment the current service
	// operates in. This is meant to be "" if used from outside a lever service.
	OwnEnvironment = os.Getenv("LEVEROS_ENVIRONMENT")
	// OwnService is the name of the current service. This is meant to be "" if
	// used from outside a lever service.
	OwnService = os.Getenv("LEVEROS_SERVICE")
	// OwnInstanceID is the name of the current instance. This is meant to be
	// "" if used from outside a lever service.
	OwnInstanceID = os.Getenv("LEVEROS_INSTANCE_ID")
)

Functions

func IsChanMethod

func IsChanMethod(name string) bool

IsChanMethod returns true if the name represents a valid streaming method name.

Types

type BytesError

type BytesError interface {
	GetBytes() []byte
	error
}

BytesError is an error that can be represented as bytes.

type Client

type Client struct {
	ForceHost string
	// contains filtered or unexported fields
}

Client is a Lever OS client. It can be used to initiate RPC's to other lever services.

func NewClient

func NewClient() (*Client, error)

NewClient creates a new Lever Client.

func (*Client) InvokeChanURL

func (client *Client) InvokeChanURL(
	leverURLStr string, args ...interface{}) (stream Stream, err error)

InvokeChanURL invokes a remote streaming method referenced by a Lever URL. The URL can be either absolute (remote environment) or relative (same environment). Example:

/<service>[/<resource>]/method (relative URL)

lever://<env>/<service>[/<resource>]/method (absolute URL)

func (*Client) InvokeURL

func (client *Client) InvokeURL(
	replyObj interface{}, leverURLStr string, args ...interface{}) (err error)

InvokeURL invokes a remote method referenced by a Lever URL. The URL can be either absolute (remote environment) or relative (same environment). Example:

/<service>[/<resource>]/method (relative URL)

lever://<env>/<service>[/<resource>]/method (absolute URL)

func (*Client) Resource

func (client *Client) Resource(
	env string, service string, resource string) *Endpoint

Resource returns an endpoint representing a Lever resource within a Lever service. If env is "" then the current environment is used (assuming you are running within a Lever instance).

func (*Client) Service

func (client *Client) Service(env string, service string) *Endpoint

Service returns an endpoint representing a Lever service. If env is "" then the current environment is used (assuming you are running within a Lever instance).

type ClientStream

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

ClientStream is the client Stream object that is returned when invoking a streaming RPC.

func (*ClientStream) Close

func (stream *ClientStream) Close() error

Close implements the Stream interface.

func (*ClientStream) Context

func (stream *ClientStream) Context() context.Context

Context implements the Stream interface.

func (*ClientStream) Receive

func (stream *ClientStream) Receive(msgObj interface{}) error

Receive implements the Stream interface.

func (*ClientStream) Send

func (stream *ClientStream) Send(msg interface{}) error

Send implements the Stream interface.

type Endpoint

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

Endpoint represents a Lever service or a Lever resource within a service. It can be used to invoke methods remotely.

func (*Endpoint) Invoke

func (endpoint *Endpoint) Invoke(
	replyObj interface{}, method string, args ...interface{}) (err error)

Invoke invokes a remote method and populates replyObj with the response if successful.

func (*Endpoint) InvokeChan

func (endpoint *Endpoint) InvokeChan(
	method string, args ...interface{}) (stream Stream, err error)

InvokeChan invokes a remote streaming method. It returns a Stream object which can be used to communicate with the Lever instance in real-time.

type RemoteByteError

type RemoteByteError struct {
	Err []byte
}

RemoteByteError is an error received as bytes after calling a remote method.

func (*RemoteByteError) Error

func (err *RemoteByteError) Error() string

func (*RemoteByteError) GetBytes

func (err *RemoteByteError) GetBytes() []byte

GetBytes returns the error as bytes.

type RemoteError

type RemoteError struct {
	Err interface{}
}

RemoteError is an error received after calling a remote method.

func (*RemoteError) Error

func (err *RemoteError) Error() string

type Server

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

Server is a server that handles Lever RPCs.

func NewServer

func NewServer() (server *Server, err error)

NewServer creates a new Server.

func (*Server) HandleRPC

func (server *Server) HandleRPC(
	ctx context.Context, rpc *core.RPC) (reply *core.RPCReply, err error)

HandleRPC is an internal method. Do not use!

func (*Server) HandleStreamingRPC

func (server *Server) HandleStreamingRPC(
	grpcStream core.LeverRPC_HandleStreamingRPCServer) error

HandleStreamingRPC is an internal method. Do not use!

func (*Server) RegisterHandler

func (server *Server) RegisterHandler(
	name string, handler interface{}) error

RegisterHandler registers a function to handle the method with provided name.

func (*Server) RegisterHandlerObject

func (server *Server) RegisterHandlerObject(obj interface{}) error

RegisterHandlerObject registers an object to handle RPCs with method names that are the same as the methods of the provided object. Private methods are ignored.

func (*Server) Serve

func (server *Server) Serve() error

Serve enters the Server's serving loop. This blocks until the server no longer serves.

func (*Server) Stop

func (server *Server) Stop()

Stop stops a Server that is currently serving.

type ServerStream

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

ServerStream is the server Stream object that is provided as the first parameter in a Lever channel method.

func (*ServerStream) Close

func (stream *ServerStream) Close() error

Close implements the Stream interface.

func (*ServerStream) Context

func (stream *ServerStream) Context() context.Context

Context implements the Stream interface.

func (*ServerStream) Receive

func (stream *ServerStream) Receive(msgObj interface{}) error

Receive implements the Stream interface.

func (*ServerStream) Send

func (stream *ServerStream) Send(msg interface{}) error

Send implements the Stream interface.

type Stream

type Stream interface {
	// Send sends a message to the other end of the channel.
	Send(msg interface{}) error
	// Receive receives the next message from the the channel and populates
	// msgObj with it. If the other end has closed then this returns io.EOF
	// (and doesn't populate msgObj).
	Receive(msgObj interface{}) error
	// Close closes this end of the channel. This means that writing is no
	// longer possible, though receiving can continue normally until the other
	// end closes the channel itself.
	Close() error
	// Context returns the context associated with the channel.
	Context() context.Context
}

Stream is either the first parameter of a Lever channel method (server) or the return value of a streaming RPC (client). It can be used to send and receive messages related to a streaming RPC.

Directories

Path Synopsis
Package admin provides convenience function for interacting with the admin service.
Package admin provides convenience function for interacting with the admin service.

Jump to

Keyboard shortcuts

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