rk-mux

module

v0.0.7 Latest Latest Go to latest Published: Jan 30, 2022 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/rookie-ninja/rk-mux

Links

Open Source Insights

README ¶

rk-mux

In testing stage!

Interceptor & bootstrapper designed for gorilla/mux web framework. Documentation.

This belongs to rk-boot family. We suggest use this lib from rk-boot.

Table of Contents generated with DocToc

Architecture
Supported bootstrap
Supported instances
Supported middlewares
Installation
Quick Start
YAML Options
- Mux
- CommonService
- Swagger
- Prometheus Client
- TV
- Static file handler
- Middlewares
  - Log
  - Metrics
  - Auth
  - Meta
  - Tracing
  - RateLimit
  - Timeout
  - CORS
  - JWT
  - Secure
  - CSRF
- Full YAML
Development Status: Testing
Build instruction
Test instruction
Contributing

Architecture

Supported bootstrap

Bootstrap	Description
YAML based	Start gorilla/mux microservice from YAML
Code based	Start gorilla/mux microservice from code

Supported instances

All instances could be configured via YAML or Code.

User can enable anyone of those as needed! No mandatory binding!

Instance	Description
mux.Router	Compatible with original gorilla/mux service functionalities
Config	Configure spf13/viper as config instance and reference it from YAML
Logger	Configure uber-go/zap logger configuration and reference it from YAML
EventLogger	Configure logging of RPC with rk-query and reference it from YAML
Credential	Fetch credentials from remote datastore like ETCD.
Cert	Fetch TLS/SSL certificates from remote datastore like ETCD and start microservice.
Prometheus	Start prometheus client at client side and push metrics to pushgateway as needed.
Swagger	Builtin swagger UI handler.
CommonService	List of common APIs.
TV	A Web UI shows microservice and environment information.
StaticFileHandler	A Web UI shows files could be downloaded from server, currently support source of local and pkger.

Supported middlewares

All middlewares could be configured via YAML or Code.

User can enable anyone of those as needed! No mandatory binding!

Middleware	Description
Metrics	Collect RPC metrics and export to prometheus client.
Log	Log every RPC requests as event with rk-query.
Trace	Collect RPC trace and export it to stdout, file or jaeger with open-telemetry/opentelemetry-go.
Panic	Recover from panic for RPC requests and log it.
Meta	Send micsroservice metadata as header to client.
Auth	Support [Basic Auth] and [API Key] authorization types.
RateLimit	Limiting RPC rate globally or per path.
Timeout	Timing out request by configuration.
CORS	Server side CORS validation.
JWT	Server side JWT validation.
Secure	Server side secure validation.
CSRF	Server side csrf validation.

Installation

go get github.com/rookie-ninja/rk-mux

Quick Start

In the bellow example, we will start microservice with bellow functionality and middlewares enabled via YAML.

Http server with gorilla/mux router
Swagger UI
CommonService
TV
Prometheus Metrics (middleware)
Logging (middleware)
Meta (middleware)

Please refer example at example/boot/simple.

1.Create boot.yaml

boot.yaml

---
mux:
  - name: greeter                     # Required
    port: 8080                        # Required
    enabled: true                     # Required
    tv:
      enabled: true                   # Optional, default: false
    prom:
      enabled: true                   # Optional, default: false
    sw:                               # Optional
      enabled: true                   # Optional, default: false
    commonService:                    # Optional
      enabled: true                   # Optional, default: false
    interceptors:
      loggingZap:
        enabled: true
      metricsProm:
        enabled: true
      meta:
        enabled: true

2.Create main.go

main.go

// Copyright (c) 2021 rookie-ninja
//
// Use of this source code is governed by an Apache-style
// license that can be found in the LICENSE file.
package main

import (
	"context"
	"fmt"
	"github.com/rookie-ninja/rk-entry/entry"
	"github.com/rookie-ninja/rk-mux/boot"
	"github.com/rookie-ninja/rk-mux/interceptor"
	"net/http"
)

// @title RK Swagger for Mux
// @version 1.0
// @description This is a greeter service with rk-boot.
func main() {
	// Bootstrap basic entries from boot config.
	rkentry.RegisterInternalEntriesFromConfig("example/boot/simple/boot.yaml")

	// Bootstrap mux entry from boot config
	res := rkmux.RegisterMuxEntriesWithConfig("example/boot/simple/boot.yaml")

	// Get MuxEntry
	muxEntry := res["greeter"].(*rkmux.MuxEntry)
	// Use *mux.Router adding handler.
	muxEntry.Router.NewRoute().Path("/v1/greeter").HandlerFunc(Greeter)

	// Bootstrap mux entry
	muxEntry.Bootstrap(context.Background())

	// Wait for shutdown signal
	rkentry.GlobalAppCtx.WaitForShutdownSig()

	// Interrupt mux entry
	muxEntry.Interrupt(context.Background())
}

// @Summary Greeter service
// @Id 1
// @version 1.0
// @produce application/json
// @Param name query string true "Input name"
// @Success 200 {object} GreeterResponse
// @Router /v1/greeter [get]
func Greeter(writer http.ResponseWriter, req *http.Request) {
	rkmuxinter.WriteJson(writer, http.StatusOK, &GreeterResponse{
		Message: fmt.Sprintf("Hello %s!", req.URL.Query().Get("name")),
	})
}

// Response.
type GreeterResponse struct {
	Message string
}

3.Start server

$ go run main.go

4.Validation