gomu

README

Gomu

Gomu is a helper tool for developing Go Micro projects.

Getting Started

Download and install Go. Version 1.16 or higher is required.

Installation is done by using the go install command.

go install github.com/asim/go-micro/cmd/gomu@latest

Let's create a new service using the new command.

gomu new service helloworld

Follow the on-screen instructions. Next, we can run the program.

cd helloworld
make proto tidy
gomu run

Finally we can call the service.

gomu call helloworld Helloworld.Call '{"name": "John"}'

That's all you need to know to get started. Refer to the Go Micro documentation for more info on developing services.

Dependencies

You will need protoc-gen-micro for code generation

• protobuf
• protoc-gen-go
• protoc-gen-micro

# Download latest proto release
# https://github.com/protocolbuffers/protobuf/releases
go get -u google.golang.org/protobuf/proto
go install github.com/golang/protobuf/protoc-gen-go@latest
go install go-micro.dev/v4/cmd/protoc-gen-micro@latest

Creating A Service

To create a new service, use the gomu new service command.

$ gomu new service helloworld
creating service helloworld

download protoc zip packages (protoc-$VERSION-$PLATFORM.zip) and install:

visit https://github.com/protocolbuffers/protobuf/releases/latest

download protobuf for go-micro:

go get -u google.golang.org/protobuf/proto
go install github.com/golang/protobuf/protoc-gen-go@latest
go install go-micro.dev/cmd/protoc-gen-micro/v4@latest

compile the proto file helloworld.proto:

cd helloworld
make proto tidy

To create a new function, use the gomu new function command. Functions differ from services in that they exit after returning.

$ gomu new function helloworld
creating function helloworld

download protoc zip packages (protoc-$VERSION-$PLATFORM.zip) and install:

visit https://github.com/protocolbuffers/protobuf/releases/latest

download protobuf for go-micro:

go get -u google.golang.org/protobuf/proto
go install github.com/golang/protobuf/protoc-gen-go@latest
go install go-micro.dev/cmd/protoc-gen-micro/v4@latest

compile the proto file helloworld.proto:

cd helloworld
make proto tidy

Jaeger

To create a new service with Jaeger integration, pass the --jaeger flag to the gomu new service or gomu new function commands. You may configure the Jaeger client using environment variables.

gomu new service --jaeger helloworld

You may invoke trace.NewSpan(context.Context).Finish() to nest spans. For example, consider the following handler implementing a greeter.

handler/helloworld.go

package helloworld

import (
    "context"

    log "go-micro.dev/v4/logger"

    "helloworld/greeter"
    pb "helloworld/proto"
)

type Helloworld struct{}

func (e *Helloworld) Call(ctx context.Context, req pb.CallRequest, rsp *pb.CallResponse) error {
    log.Infof("Received Helloworld.Call request: %v", req)
    rsp.Msg = greeter.Greet(ctx, req.Name)
    return nil
}

greeter/greeter.go

package greeter

import (
    "context"
    "fmt"

    "github.com/asim/go-micro/cmd/gomu/debug/trace"
)

func Greet(ctx context.Context, name string) string {
    defer trace.NewSpan(ctx).Finish()
    return fmt.Sprint("Hello " + name)
}

Skaffold

To create a new service with Skaffold files, pass the --skaffold flag to the gomu new service or gomu new function commands.

gomu new service --skaffold helloworld

Running A Service

To run a service, use the gomu run command to build and run your service continuously.

$ gomu run
2021-08-20 14:05:54  file=v3@v3.5.2/service.go:199 level=info Starting [service] helloworld
2021-08-20 14:05:54  file=server/rpc_server.go:820 level=info Transport [http] Listening on [::]:34531
2021-08-20 14:05:54  file=server/rpc_server.go:840 level=info Broker [http] Connected to 127.0.0.1:44975
2021-08-20 14:05:54  file=server/rpc_server.go:654 level=info Registry [mdns] Registering node: helloworld-45f43a6f-5fc0-4b0d-af73-e4a10c36ef54

With Docker

To run a service with Docker, build the Docker image and run the Docker container.

$ make docker
$ docker run helloworld:latest
2021-08-20 12:07:31  file=v3@v3.5.2/service.go:199 level=info Starting [service] helloworld
2021-08-20 12:07:31  file=server/rpc_server.go:820 level=info Transport [http] Listening on [::]:36037
2021-08-20 12:07:31  file=server/rpc_server.go:840 level=info Broker [http] Connected to 127.0.0.1:46157
2021-08-20 12:07:31  file=server/rpc_server.go:654 level=info Registry [mdns] Registering node: helloworld-31f58714-72f5-4d12-b2eb-98f66aea7a34

With Skaffold

When you've created your service using the --skaffold flag, you may run the Skaffold pipeline using the skaffold command.

skaffold dev

Creating A Client

To create a new client, use the gomu new client command. The name is the service you'd like to create a client project for.

$ gomu new client helloworld
creating client helloworld
cd helloworld-client
make tidy

You may optionally pass the fully qualified package name of the service you'd like to create a client project for.

$ gomu new client github.com/auditemarlow/helloworld
creating client helloworld
cd helloworld-client
make tidy

Running A Client

To run a client, use the gomu run command to build and run your client continuously.

$ gomu run
2021-09-03 12:52:23  file=helloworld-client/main.go:33 level=info msg:"Hello John"

Generating Files

To generate Go Micro project template files after the fact, use the gomu generate command. It will place the generated files in the current working directory.

$ gomu generate skaffold
skaffold project template files generated

Listing Services

To list services, use the gomu services command.

$ gomu services
helloworld

Describing A Service

To describe a service, use the gomu describe service command.

$ gomu describe service helloworld
{
  "name": "helloworld",
  "version": "latest",
  "metadata": null,
  "endpoints": [
    {
      "name": "Helloworld.Call",
      "request": {
        "name": "CallRequest",
        "type": "CallRequest",
        "values": [
          {
            "name": "name",
            "type": "string",
            "values": null
          }
        ]
      },
      "response": {
        "name": "CallResponse",
        "type": "CallResponse",
        "values": [
          {
            "name": "msg",
            "type": "string",
            "values": null
          }
        ]
      }
    }
  ],
  "nodes": [
    {
      "id": "helloworld-9660f06a-d608-43d9-9f44-e264ff63c554",
      "address": "172.26.165.161:45059",
      "metadata": {
        "broker": "http",
        "protocol": "mucp",
        "registry": "mdns",
        "server": "mucp",
        "transport": "http"
      }
    }
  ]
}

You may pass the --format=yaml flag to output a YAML formatted object.

$ gomu describe service --format=yaml helloworld
name: helloworld
version: latest
metadata: {}
endpoints:
- name: Helloworld.Call
  request:
    name: CallRequest
    type: CallRequest
    values:
    - name: name
      type: string
      values: []
  response:
    name: CallResponse
    type: CallResponse
    values:
    - name: msg
      type: string
      values: []
nodes:
- id: helloworld-9660f06a-d608-43d9-9f44-e264ff63c554
  address: 172.26.165.161:45059
  metadata:
    broker: http
    protocol: mucp
    registry: mdns
    server: mucp
    transport: http

Calling A Service

To call a service, use the gomu call command. This will send a single request and expect a single response.

$ gomu call helloworld Helloworld.Call '{"name": "John"}'
{"msg":"Hello John"}

To call a service's server stream, use the gomu stream server command. This will send a single request and expect a stream of responses.

$ gomu stream server helloworld Helloworld.ServerStream '{"count": 10}'
{"count":0}
{"count":1}
{"count":2}
{"count":3}
{"count":4}
{"count":5}
{"count":6}
{"count":7}
{"count":8}
{"count":9}

To call a service's bidirectional stream, use the gomu stream bidi command. This will send a stream of requests and expect a stream of responses.

$ gomu stream bidi helloworld Helloworld.BidiStream '{"stroke": 1}' '{"stroke": 2}' '{"stroke": 3}'
{"stroke":1}
{"stroke":2}
{"stroke":3}

License

This software is published under the MIT license.