nilgo

README

nilgo 🐃

Nilgo provides an out-of-the-box, cloud-native, production-ready, minimalist Go application framework with pre-customized configuration, log, and telemetry for major Cloud providers.

Nilgo is Nilgai in brezhoneg. The nilgai (literally meaning "blue cow") is the largest Asian antelope and is ubiquitous across the northern Indian subcontinent.

Installation

go get github.com/ktong/nilgo

Quick Start

It's usually used in main function to bootstrap the application. Below code runs gRPC server on Google Cloud Platform.

package main

import (
  "google.golang.org/grpc"

  "github.com/ktong/nilgo"
  "github.com/ktong/nilgo/gcp"
  ngrpc "github.com/ktong/nilgo/grpc"
)

func main() {
  nilgo.Run(
    otel.WithTrace(),
    otel.WithMetric(),
    gcp.Options(
      gcp.WithProfiler(),
    ),
    func(ctx context.Context) error {
      // initialize your gRPC server implementation here.
      // It should use defer for resources clean up.

      return ngrpc.NewServer(
        ngrpc.WithTelemetry(),
      )(
        func(srv *grpc.Server) {
          // Register your gRPC server implementation here.
        },
      )(ctx)
    },
  )
}

Typical Usage

Configuration

nilgo unmarshal values has provided prefix to a string, struct, map, etc,

Example:

// It would provide sensible defaults for the most common cases.
cfg := serverConfig {
    Port: 8080
    Name: "default"
}

// Unmarshal load overrides from config file, env variable, and flags (if application).
err := config.Unmarshal("server", &cfg)

Logging

nilgo leverages logr to encourage attaching structured information instead of unstructured format strings.

Example:

log.FromContext(ctx).Info("starting up", "port", port)
log.FromContext(ctx).Error(err, "failed to open the pod bay door", "user", user)

Telemetry

nilgo integrates OpenTelemetry for tracing and metrics.

Metric Example:

counter, err := otel.Meter("instrumentation name").NewInt64Counter("test")
if err != nil {
    // Handle error.
}					

counter.Add(ctx, 1)

Trace Example:

ctx, span := otel.Tracer("tracer name").Start(ctx, "test")
defer span.End()

Implementation principles

Don't Panic

Nilgo encourages explicit error handling instead of implicit panic, so all code has a determined execution path. Conversely, nilgo also does not recover any panic from dependencies unless it clearly understand how to handle it.

Every Goroutine Matters

Nilgo guarantees every single goroutine shutdown gracefully. It leverages goleak detecting goroutine leaking.

Documentation

Overview

Package nilgo runs application on Cloud with pre-configured logger, config, telemetry, graceful shutdown, etc.

It's usually used in main() function to bootstrap the application like following code:

func main() {
  nilgo.Run(
    options_and_runners...,
  )
}

Index

• func Run(opts ...interface{})

Examples

• Run

Functions

func Run

func Run(opts ...interface{})

Run runs app synchronously with provided options.

The runners passed in are running parallel without explicit order, which means it should not have temporal dependency between runners.

The running can be interrupted if any runner returns non-nil error, or it receives an os.Signal specified via WithSignals. It waits all runners return unless it's forcefully killed by os.

It panics on first non-nil error (if any) received. It does not recover panic, which causes running crashes if any panic happens without recovery in runner.

For now, it only can be one of the following types for opts:

• nilgo.Option
• log.Option
• config.Option
• otel.Option
• func(context.Context) error

Example

package main

import (
	"context"
	"testing/fstest"

	"go.uber.org/zap"

	"github.com/ktong/nilgo"
	"github.com/ktong/nilgo/config"
	"github.com/ktong/nilgo/log"
)

func main() {
	cfg := fstest.MapFS{
		"config.yaml": {
			Data: []byte("app:\n  user: cfg"),
		},
	}

	nilgo.Run(
		config.WithFile("config.yaml"),
		config.WithFS(cfg),
		log.WithZapLogger(zap.NewExample()),
		func(ctx context.Context) error {
			var user string
			if err := config.Unmarshal("app.user", &user); err != nil {
				return err
			}

			log.FromContext(ctx).Info("example log", "user", user)

			return nil
		},
	)

}

Output:

{"level":"info","msg":"example log","user":"cfg"}