Back to godoc.org

Package api

v0.1.1
Latest Go to latest

The latest major version is .

Published: May 20, 2016 | License: Apache-2.0 | Module: github.com/leveros/leveros

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

const PackageName = "api"

PackageName is the name of this package.

Variables

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")
)

func IsChanMethod

func IsChanMethod(name string) bool

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

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.

Package Files

Documentation was rendered with GOOS=linux and GOARCH=amd64.

Jump to identifier

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to identifier