donutloop / xservice

Framework to generate web APIs

Introduction

xservice is a simple generator library used for generating services quickly and easily for an proto buffer. The purpose of this project is to generate of a lot of the basic boilerplate associated with writing API services so that you can focus on writing business logic.

Making a golang xservice

To make a golang service:

1. Define your service in a Proto file.
2. Use the protoc command to generate go code from the Proto file, it will generate an interface, a server and some server utils (to easily start an http listener).
3. Implement the generated interface to implement the service.

For example, a HelloWorld Proto file:

syntax = "proto3";
package donutloop.xservice.example.helloworld;
option go_package = "helloworld";

service HelloWorld {
  rpc Hello(HelloReq) returns (HelloResp);
}

message HelloReq {
  string subject = 1;
}

message HelloResp {
  string text = 1;
}

From which xservice can auto-generate this interface (running the protoc command):

type HelloWorld interface {
	Hello(context.Context, *HelloReq) (*HelloResp, error)
}

You provide the implementation:

package main

import (
	"context"
	"net/http"

	pb "github.com/donutloop/xservice-example/helloworld"
)

type HelloWorldServer struct{}

func (s *HelloWorldServer) Hello(ctx context.Context, req *pb.HelloReq) (*pb.HelloResp, error) {
	return &pb.HelloResp{Text: "Hello " + req.Subject}, nil
}

// Run the implementation in a local server
func main() {
	handler := pb.NewHelloWorldServer(&HelloWorldServer{}, nil)
	// You can use any mux you like - NewHelloWorldServer gives you an http.Handler.
	mux := http.NewServeMux()
	// The generated code includes a const, <ServiceName>PathPrefix, which
	// can be used to mount your service on a mux.
	mux.Handle(pb.HelloWorldPathPrefix, handler)
	http.ListenAndServe(":8080", mux)
}

Now you can just use the auto-generated JSON or Protobuffer Client to make remote calls to your new service:

JSON

package main

import (
	"context"
	"fmt"
	"net/http"

	pb "github.com/donutloop/xservice-example/helloworld"
)

func main() {
	client := pb.NewHelloWorldJSONClient("http://localhost:8080", &http.Client{})

	resp, err := client.Hello(context.Background(), &pb.HelloReq{Subject: "World"})
	if err == nil {
		fmt.Println(resp.Text) // prints "Hello World"
	}
}

Protobuffer

package main

import (
	"context"
	"fmt"
	"net/http"

	pb "github.com/donutloop/xservice-example/helloworld"
)

func main() {
	client := pb.NewHelloWorldProtobufferClient("http://localhost:8080", &http.Client{})

	resp, err := client.Hello(context.Background(), &pb.HelloReq{Subject: "World"})
	if err == nil {
		fmt.Println(resp.Text) // prints "Hello World"
	}
}

QuickStart for developers

Please refer docs/DeveloperQuickStart.md

Roadmap

• Multi language support

Contribution

Thank you for considering to help out with the source code! We welcome contributions from anyone on the internet, and are grateful for even the smallest of fixes!

If you'd like to contribute to xservice, please fork, fix, commit and send a pull request for the maintainers to review and merge into the main code base to ensure those changes are in line with the general philosophy of the project and/or get some early feedback which can make both your efforts much lighter as well as our review and merge procedures quick and simple.

Please read and follow our Contributing.

Code of Conduct

Please read and follow our Code of Conduct.

Credits

• Parts of xservice thinking comes from twirp (https://github.com/twitchtv/twirp)

xservice's Issues

grpc-web

have you seen grpcweb ?

It is similar and gens the code for the web client and converts calls to web sockets.

Hello Marcel

No NewXXXProtobufClient method

Description

The generated protobuf files currently don't have "NewXXXProtobufClient" method, only a JSON client exists, also the generated code can only handle json content-types.

Steps to reproduce the issue:

1. Follow the example given in the readme
2. See compile error

XService Version:

• master
• 0.1.0