Forem: L2ncE

Go microservice project based multiple technology stacks | Recommended open source projects

L2ncE — Mon, 23 Jan 2023 13:57:43 +0000

FreeCar

FreeCar is a full-stack microservice project based on Hertz and Kitex, welcome Star.

Hertz

Hertz is an ultra-large-scale enterprise-level microservice HTTP framework, featuring high ease of use, easy expansion, and low latency etc.

Hertz uses the self-developed high-performance network library Netpoll by default. In some special scenarios, Hertz has certain advantages in QPS and latency compared to go net.

In internal practice, some typical services, such as services with a high proportion of frameworks, gateways and other services, after migrating Hertz, compared to the Gin framework, the resource usage is significantly reduced, CPU usage is reduced by 30%-60% with the size of the traffic.

For more details, see cloudwego/hertz.

technology stack

Function	Implementation
HTTP Framework	Hertz
RPC Framework	Kitex
Database	MongoDB, MySQL
Configuration Center	Nacos
Service Discovery Center	Nacos
Message Queue	RabbitMQ
Link Tracking	Jaeger
Cluster Monitoring	Prometheus
Current limiting middleware	hertz-contrib/limiter
Deployment	docker-compose
Object Storage	Tencent Cloud COS
CI	GitHub Actions

Project Architecture

Call relationship

Technology Architecture

Service Relationship

Display

Directory Introduction

Catalog	Introduction
Server	Core part of the project
Shared	Reusable Code
Static	WeChat applet code

Service Introduce

Catalog	Introduce
API	Hertz-based Gateway Service
Auth	User Authentication Service
Blob	Services Related to Pictures and Tencent Cloud COS
Car	Car Service
Profile	Profile and Picture Recognition Services
Trip	Trip Service

Quick Start

Start dependence

make start

Configure Nacos

Access http://127.0.0.1:8848/nacos/index.html#/login on the browser to log in.

For the default namespace and configuration groups, please refer to each config.yaml configuration file.

For detailed configuration of the configuration center, see.

Generate data table

make migrate

Start HTTP service

make api

Start the microservice

make auth
make blobs
make a car
make profile
make a trip

Jaeger

Visit http://127.0.0.1:16686/ on your browser

Prometheus

Visit http://127.0.0.1:3000/ on your browser

API requests

The project's API request example see details.

Development Guide

It is very difficult to understand this project by directly reading the source code. Here is a development guide for developers to quickly understand and get started with this project, including frameworks such as Kitex and Hertz.

Preparation

Use the commands in the quick start to quickly start the required tools and environment. If you need special customization, please modify the contents of docker-compose.yaml and Nacos configuration.

IDL

Before development, we need to define the IDL file, where hz
Provides developers with many customized api annotations.

Sample code:

namespace go auth

struct LoginRequest {
     1: string code
}

struct LoginResponse {
     1: i64 accountID
}

service AuthService {
     LoginResponse Login(1: LoginRequest req)
}

Code Generation

Kitex

Execute under the new service directory, only need to change the service name and IDL path each time.

Server

kitex -service auth -module github.com/CyanAsterisk/FreeCar ./../../idl/auth.thrift

client

kitex -module github.com/CyanAsterisk/FreeCar ./../../idl/auth.thrift

Note:

Use -module github.com/CyanAsterisk/FreeCar This parameter is used to specify the Go module to which the generated code belongs to avoid path problems.
When the current service needs to call other services, a client file needs to be generated.

Hertz

Initialization

hz new -idl ./../../idl/api.proto -mod github.com/CyanAsterisk/FreeCar/server/cmd/api

renew

hz update -I -idl ./../../idl/api.proto

Note:

Use -module github.com/CyanAsterisk/FreeCar/server/cmd/api This parameter is used to specify the Go module to which the generated code belongs to avoid path problems.

Business Development

After the code is generated, some necessary components need to be added to the project. Since the api layer does not need to be added again, the following mainly explains about Kitex-Server
section, the code is located under server/cmd.

Config

Refer to server/cmd/auth/config for the configuration structure of microservices.

Global

Refer to server/cmd/auth/global to provide globally callable methods for microservices.

Initialize

Refer to server/cmd/auth/initialize to provide the initialization function of the necessary components, among which nacos.go flag.go logger.go are required.

Tool

Refer to server/cmd/auth/tool to provide tool functions for microservices, where port.go is required.

API

When writing the business logic of the gateway layer, you only need to update the IDL and the new microservice client code each time. If you need to add new components, you can add them directly. The project is highly pluggable, and the architecture is similar to the microservice layer.

The business logic of the gateway layer is under server/cmd/api/biz, and most of the code will be automatically generated. If you need to add a new route separately, you need to go to server/cmd/api/router.go.

Regarding the use of middleware, you only need to add middleware logic in server/cmd/api/biz/router/api/middleware.go.

License

FreeCar is open source under the GNU General Public License version 3.0.

Summarize

This project still takes a lot of time, everyone is welcome to learn, if Star is our greatest encouragement!

Reference

Hertz supports HTTP3 Interpretation of v0.5.0 version

L2ncE — Mon, 16 Jan 2023 07:01:22 +0000

In version 0.5.0 of Hertz, in addition to regular iterative optimization, we also brought several important features.

Network layer and protocol layer support stream-based interface

https://github.com/cloudwego/hertz/pull/467

In the Hertz v0.5.0 version, we have further enhanced the scalability of the Hertz transport layer & protocol layer, supporting the seamless connection of the stream-based transport layer protocol QUIC, and the HTTP3 protocol built on top of it.
In addition, on this basis, we have added and improved functions such as "ALPN" (application layer protocol negotiation), "QUIC/TLS parallel monitoring" (QUIC/TLS parallel monitoring), "Alt-Svc" (alternative service).

Major Changes

Transport layer

On the basis of ensuring compatibility performance, we have added an abstract stream-based network connection interface StreamConn, and adjusted the interaction logic between the transport layer and the protocol layer to achieve the correct protocol layer for the distribution of connection types Processing (protocol server).
For scenarios that need to monitor TCP (TLS) and UDP (QUIC) at the same time, we provide a WithAltTransporter option, which facilitates passing the backup transporter to the main transporter, and facilitates the ability to monitor QUIC/TLS in parallel.

Protocol Layer

Support adding a stream-based protocol layer implementation (protocol server) StreamServer, so as to build a corresponding processing protocol (HTTP/3) on top of the newly added stream-based transport layer extension.
In order to facilitate the configuration of alternative service meta-information for a main protocol (HTTP/3), ProtocolSuite exposes the SetAltHeader interface.
At the same time, we also designed the ALPN capability for StreamConn, so as to provide the ability of protocol negotiation in QUIC.

Common layer

At the same time, we have added an auxiliary function that can convert with the Golang standard Handler in the general layer, so as to quickly port the implementation based on the Golang standard Handler to Hertz. The QUIC & HTTP/3 extension based on quic-go provided later /pull/1), the capabilities provided by this function are used.

Feature Status

The Hertz core library capability has been released, and the specific implementation will be released in the form of extension package, welcome to try~

For more detailed design instructions, please refer to: Hertz supports QUIC & HTTP/3

Scaffolding tools support generating hertz client code

https://github.com/cloudwego/hertz/pull/471

In the v0.5.0 version of the scaffolding tool (Hz), we support the function of automatically generating the hertz client code based on IDL, and realize the one-click call of the HTTP request in the form of an RPC call.
Instructions:

For details, see: https://github.com/cloudwego/hertz-examples/tree/main/hz_client

Define the IDL

namespace go toutiao.middleware.hzClient
struct QueryReq {
     1: string QueryValue (api. query="query1");
}
struct Resp {
     1: string Resp;
}
service Hertz121 {
     Resp QueryMethod(1: QueryReq request) (api. get="/query", api. handler_path="get");
}(
     api.base_domain="http://127.0.0.1:8888";
)

Generate code

Based on the above IDL, the server and client codes can be generated separately:

Server:

hz new --idl=psm.thrift --handler_by_method -t=template=slim

Client:

hz client --idl=psm.thrift --model_dir=hertz_gen -t=template=slim --client_dir=hz_client

Call the client code to initiate an HTTP request to realize the intercommunication between the client end and the server end

Full Release Note

The complete Release Note can refer to:

Hertz: https://github.com/cloudwego/hertz/releases/tag/v0.5.0
Hz(scaffolding): https://github.com/cloudwego/hertz/releases/tag/cmd%2Fhz%2Fv0.5.0

Load balancing expansion from 0 to 1

L2ncE — Thu, 22 Dec 2022 02:56:59 +0000

In Hertz's service discovery, it can be configured to use load balancing to achieve service high availability and traffic balancing.

Hertz

Hertz is an ultra-large-scale enterprise-level microservice HTTP framework, featuring high ease of use, easy expansion, and low latency etc.

Hertz uses the self-developed high-performance network library Netpoll by default. In some special scenarios, Hertz has certain advantages in QPS and latency compared to go net.

For more details, see cloudwego/hertz.

Weighted Random Algorithm

Load balancing in Hertz is implemented using a weighted random algorithm, defined in pkg/app/client/loadbalance/weight_random.go. First we need to define the weightedBalancer structure.

type weightedBalancer struct {
    cachedWeightInfo sync.Map
    sfg singleflight.Group
}

It contains a sync.Map type cache weight information and a singleflight.Group . We need to make weightedBalancer implement the four methods defined in Loadbalancer.

calcWeightInfo

This method is one of the core methods of this algorithm. We will use this method to return a weight information structure, which contains instances, their respective weights and total weights.

type weightInfo struct {
    instances [] discovery.Instance
    entries []int
    weightSum int
}

First, we declare a variable w of type *weightInfo , initialize instances to the incoming instance, initialize weightSum to 0, and initialize entries to an int type slice whose length is the number of instances.

w := &weightInfo{
   instances: make([]discovery.Instance, len(e.Instances)),
   weightSum: 0,
   entries: make([]int, len(e.Instances)),
}

Next, the core part of this method, we use the subscript idx to traverse the incoming instance, when the weight of the instance is greater than 0, assign the subscripted instance to the instance w whose subscript is cnt, and the weight is the same, and then assign this weight Added to weightSum. If less than 0, log warnings. Finally, assign the instances with subscripts 0 to cnt to w.instances.

var cnt int

for idx := range e.Instances {
   weight := e.Instances[idx].Weight()
   if weight > 0 {
     w.instances[cnt] = e.Instances[idx]
     w.entries[cnt] = weight
     w.weightSum += weight
     cnt++
   } else {
     hlog.SystemLogger().Warnf("Invalid weight=%d on instance address=%s", weight, e.Instances[idx].Address())
   }
}

w.instances = w.instances[:cnt]

return w

It is worth mentioning that why are there two subscripts recorded separately? Because when weight is not greater than 0, there will be null values in the slice where w stores instances. The next four methods implement the methods defined in LoadBalancer respectively.

Pick

We will first use the Load method to check whether the incoming CacheKey exists, and if it does not exist, we will call the Do method in singleflight.Group, Do will execute and return the result of the given function, ensuring that only for Execute once for the given Key. If a duplicate key is entered, the duplicate call will wait for the original call to complete and receive the same result. According to the above analysis of calWeightInfo, we will get a value of type *weightInfo and assign it to wi (at this time, wi is a variable of interface type).

wi, ok := wb.cachedWeightInfo.Load(e.CacheKey)
if !ok {
    wi, _, _ = wb.sfg.Do(e.CacheKey, func() (interface{}, error) {
        return wb.calcWeightInfo(e), nil
    })
    wb.cachedWeightInfo.Store(e.CacheKey, wi)
}

After that, we will perform the operation when the CacheKey exists, first convert wi to *weightInfo type through interface assertion and assign it to w . When the total weight value is less than 0, we will return empty, otherwise we will call the Intn function in the fastrant package to obtain a random weight, traverse the instance of w through a for loop, and subtract this weight from the randomly obtained weight each time The weight of the instance traversed at the time, and finally returns the instance traversed at this time when the random weight is less than 0.

w := wi.(*weightInfo)
if w.weightSum <= 0 {
   return nil
}

weight := fastrand.Intn(w.weightSum)
for i := 0; i < len(w.instances); i++ {
   weight -= w. entries[i]
   if weight < 0 {
     return w.instances[i]
   }
}

Rebalance

The Rebalance method will directly pass the CacheKey and the weightInfo obtained by the calcWeightInfo method into the Store method.

// Rebalance implements the Loadbalancer interface.
func (wb *weightedBalancer) Rebalance(e discovery. Result) {
    wb.cachedWeightInfo.Store(e.CacheKey, wb.calcWeightInfo(e))
}

Delete

The Delete method will call the Delete method in the sync library to delete the incoming CacheKey directly.

// Delete implements the Loadbalancer interface.
func (wb *weightedBalancer) Delete(cacheKey string) {
    wb.cachedWeightInfo.Delete(cacheKey)
}

Name

The Name method will directly return the name of the algorithm which is "weight_random" .

func (wb *weightedBalancer) Name() string {
    return "weight_random"
}

Round Robin Algorithm

In the loadbalance extension library, a load balancing implementation based on the polling algorithm is also provided. Similarly, the implementation of roundRobinBalancer needs to be defined first.

type roundRobinBalancer struct {
    cachedInfo sync.Map
    sfg singleflight.Group
}

It contains a sync.Map type cache information and a singleflight.Group . We need to make roundRobinBalancer implement the four methods defined in Loadbalancer.

roundRobinInfo

Because the polling algorithm does not require weights, the structure is much simpler than the weighted random algorithm. The structure will contain the service instance and the index of the service for polling implementation.

type roundRobinInfo struct {
    instances [] discovery.Instance
    indexuint32
}

Pick

Similar to the weighted random algorithm, we also have a similar logic for judging whether the CacheKey exists. The difference from the weighted random algorithm is that the index will be set to 0 during initialization.

ri, ok := rr.cachedInfo.Load(e.CacheKey)
if !ok {
   ri, _, _ = rr.sfg.Do(e.CacheKey, func() (interface{}, error) {
     return &roundRobinInfo{
       instances: e. Instances,
       index: 0,
     }, nil
   })
   rr.cachedInfo.Store(e.CacheKey, ri)
}

The next step is the main logic of the polling algorithm. First, if no instance is passed in, return empty, then add 1 to the previous index value, use atomic locks to prevent concurrent data competition, and finally calculate the latest index reached by polling.

r := ri.(*roundRobinInfo)
if len(r.instances) == 0 {
   return nil
}

newIdx := atomic.AddUint32(&r.index, 1)
return r.instances[(newIdx-1)%uint32(len(r.instances))]

Rebalance

The Rebalance method will directly pass the CacheKey and the initialized roundRobinInfo into the Store method.

// Rebalance implements the Loadbalancer interface.
func (rr *roundRobinBalancer) Rebalance(e discovery. Result) {
    rr.cachedInfo.Store(e.CacheKey, &roundRobinInfo{
        instances: e. Instances,
        index: 0,
    })
}

Delete

The Delete method will call the Delete method in the sync library to delete the incoming CacheKey directly.

// Delete implements the Loadbalancer interface.
func (rr *roundRobinBalancer) Delete(cacheKey string) {
    rr.cachedInfo.Delete(cacheKey)
}

Name

The Name method will directly return the name of the algorithm which is "round_robin" .

// Name implements the Loadbalancer interface.
func (rr *roundRobinBalancer) Name() string {
    return "round_robin"
}

How to use

Server

package main

import (
    "context"

    "github.com/cloudwego/hertz/pkg/app"
    "github.com/cloudwego/hertz/pkg/app/server"
    "github.com/cloudwego/hertz/pkg/app/server/registry"
    "github.com/cloudwego/hertz/pkg/common/utils"
    "github.com/cloudwego/hertz/pkg/protocol/consts"
    "github.com/hertz-contrib/registry/etcd"
)

func main() {
    r, err := etcd.NewEtcdRegistry([]string{"127.0.0.1:2379"})
    if err != nil {
        panic(err)
    }
    addr := "127.0.0.1:8888"
    h := server.Default(
        server.WithHostPorts(addr),
        server.WithRegistry(r, &registry.Info{
            ServiceName: "hertz.test.demo",
            Addr:        utils.NewNetAddr("tcp", addr),
            Weight:      10,
            Tags:        nil,
        }))
    h.GET("/ping", func(_ context.Context, ctx *app.RequestContext) {
        ctx.JSON(consts.StatusOK, utils.H{"ping": "pong2"})
    })
    h.Spin()
}

Using Nacos as our service discovery center, call the registry extension to build the simplest Hertz Server. Open three at the same time and run on different ports to simulate different servers.

Client

package main

import (
    "context"

    "github.com/cloudwego/hertz/pkg/app/client"
    "github.com/cloudwego/hertz/pkg/app/middlewares/client/sd"
    "github.com/cloudwego/hertz/pkg/common/config"
    "github.com/cloudwego/hertz/pkg/common/hlog"
    "github.com/hertz-contrib/registry/etcd"
)

func main() {
    cli, err := client.NewClient()
    if err != nil {
        panic(err)
    }
    r, err := etcd.NewEtcdResolver([]string{"127.0.0.1:2379"})
    if err != nil {
        panic(err)
    }
    cli.Use(sd.Discovery(r))
    for i := 0; i < 10; i++ {
        status, body, err := cli.Get(context.Background(), nil, "http://hertz.test.demo/ping", config.WithSD(true))
        if err != nil {
            hlog.Fatal(err)
        }
        hlog.Infof("HERTZ: code=%d,body=%s", status, string(body))
    }
}

The weighted random algorithm is used by default, and the polling algorithm is configured here for service discovery.

Test

2022/12/22 10:21:34.117821 main.go:50: [Info] code=200,body={"addr":"127.0.0.1:8003"}
2022/12/22 10:21:34.118488 main.go:50: [Info] code=200,body={"addr":"127.0.0.1:8001"}
2022/12/22 10:21:34.119135 main.go:50: [Info] code=200,body={"addr":"127.0.0.1:8002"}
2022/12/22 10:21:34.119339 main.go:50: [Info] code=200,body={"addr":"127.0.0.1:8003"}
2022/12/22 10:21:34.119518 main.go:50: [Info] code=200,body={"addr":"127.0.0.1:8001"}
2022/12/22 10:21:34.119721 main.go:50: [Info] code=200,body={"addr":"127.0.0.1:8002"}
2022/12/22 10:21:34.119929 main.go:50: [Info] code=200,body={"addr":"127.0.0.1:8003"}
2022/12/22 10:21:34.120109 main.go:50: [Info] code=200,body={"addr":"127.0.0.1:8001"}
2022/12/22 10:21:34.120243 main.go:50: [Info] code=200,body={"addr":"127.0.0.1:8002"}
2022/12/22 10:21:34.120384 main.go:50: [Info] code=200,body={"addr":"127.0.0.1:8003"}

It can be seen from the test results that the address to be accessed is selected by polling, and the test is successful.

Reference

cloudwego/hertz

hertz-contrib/loadbalance

hertz-contrib/registry

Golang CSRF Defense in Practice

L2ncE — Sun, 04 Dec 2022 08:17:14 +0000

Hertz

Hertz is an ultra-large-scale enterprise-level microservice HTTP framework, featuring high ease of use, easy expansion, and low latency etc.

Hertz uses the self-developed high-performance network library Netpoll by default. In some special scenarios, Hertz has certain advantages in QPS and latency compared to go net.

For more details, see cloudwego/hertz.

CSRF

Cross-site request forgery (English: Cross-site request forgery), also known as one-click attack or session riding, usually abbreviated as CSRF or XSRF, is an attack method that coerces users to perform unintended operations on the currently logged-in web application. Compared with cross-site scripting (XSS), XSS utilizes the user's trust in the specified website, and CSRF utilizes the website's trust in the user's web browser.

Hertz CSRF in action

Using a reverse proxy in Hertz requires pulling the CSRF extension provided by the community.

$ go get github.com/hertz-contrib/csrf

Basic use

package main

import (
    "context"

    "github.com/cloudwego/hertz/pkg/app"
    "github.com/cloudwego/hertz/pkg/app/server"
    "github.com/hertz-contrib/csrf"
    "github.com/hertz-contrib/sessions"
    "github.com/hertz-contrib/sessions/cookie"
)

func main() {
    h := server.Default()

    store := cookie.NewStore([]byte("secret"))
    h.Use(sessions.New("session", store))
    h.Use(csrf.New())

    h.GET("/protected", func(c context.Context, ctx *app.RequestContext) {
        ctx.String(200, csrf.GetToken(ctx))
    })

    h.POST("/protected", func(c context.Context, ctx *app.RequestContext) {
        ctx.String(200, "CSRF token is valid")
    })

    h.Spin()
}

First, we call sessions to expand and customize a session for testing, because subsequent tokens are generated through sessions. Then use the CSRF middleware directly.

We register two routes for testing, first use the GET method to call the GetToken() function to obtain the token generated by the CSRF middleware. Since we did not customize the KeyLookup option, the default value is header:X-CSRF-TOKEN, we put the obtained token into the header whose Key is X-CSRF-TOKEN, if If the token is invalid or the Key value is set incorrectly, calling ErrorFunc will return an error.

Test

$ curl 127.0.0.1:8888/protected

UMhM-eqB9CYjeuZO5o-9wJsQhb8KLQUpcRlYQnYagT4=

$ curl -X POST 127.0.0.1:8888/protected -H "X-CSRF-TOKEN=UMhM-eqB9CYjeuZO5o-9wJsQhb8KLQUpcRlYQnYagT4="

CSRF token is valid

Custom configuration

Configuration Item	Default	Description
Secret	"csrfSecret"	Used to generate tokens (required configuration)
IgnoreMethods	"GET", "HEAD", "OPTIONS", "TRACE"	Ignored methods will be treated as not requiring CSRF protection
Next	nil	Next defines a function that, when true, skips the CSRF middleware.
KeyLookup	header: X-CSRF-TOKEN	KeyLookup is a string of the form ":" used to create an Extractor that extracts the token from the request.
ErrorFunc	`func(ctx context.Context, c *app.RequestContext) { panic(c.Errors.Last()) }`	ErrorFunc is executed when app.HandlerFunc returns an error
Extractor	Created based on KeyLookup	Extractor returns csrf token. If set, it will be used instead of KeyLookup based Extractor.

WithSecret

package main

import (
    "context"

    "github.com/cloudwego/hertz/pkg/app"
    "github.com/cloudwego/hertz/pkg/app/server"
    "github.com/hertz-contrib/csrf"
    "github.com/hertz-contrib/sessions"
    "github.com/hertz-contrib/sessions/cookie"
)

func main() {
    h := server.Default()

    store := cookie.NewStore([]byte("store"))
    h.Use(sessions.New("csrf-session", store))
    h.Use(csrf.New(csrf.WithSecret("your_secret")))

    h.GET("/protected", func(c context.Context, ctx *app.RequestContext) {
        ctx.String(200, csrf.GetToken(ctx))
    })

    h.POST("/protected", func(c context.Context, ctx *app.RequestContext) {
        ctx.String(200, "CSRF token is valid")
    })
    h.Spin()
}

WithSecret is used to help users set a custom secret for issuing tokens. The security of token generation can be improved by customizing the secret.

WithIgnoredMethods

package main

import (
    "context"

    "github.com/cloudwego/hertz/pkg/app"
    "github.com/cloudwego/hertz/pkg/app/server"
    "github.com/hertz-contrib/csrf"
    "github.com/hertz-contrib/sessions"
    "github.com/hertz-contrib/sessions/cookie"
)

func main() {
    h := server.Default()

    store := cookie.NewStore([]byte("secret"))
    h.Use(sessions.New("session", store))
    h.Use(csrf.New(csrf.WithIgnoredMethods([]string{"GET", "HEAD", "TRACE"})))

    h.GET("/protected", func(c context.Context, ctx *app.RequestContext) {
        ctx.String(200, csrf.GetToken(ctx))
    })

    h.OPTIONS("/protected", func(c context.Context, ctx *app.RequestContext) {
        ctx.String(200, "success")
    })
    h.Spin()
}

In RFC7231, GET, HEAD, OPTIONS, and TRACE methods are recognized as safe methods, so CSRF middleware is not used in these four methods by default. If you have other requirements during use, you can configure the ignored method. In the above code, the ignore of the OPTIONS method is canceled, so direct access to this interface through the OPTIONS method is not allowed.

WithErrorFunc

package main

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

    "github.com/cloudwego/hertz/pkg/app"
    "github.com/cloudwego/hertz/pkg/app/server"
    "github.com/hertz-contrib/csrf"
    "github.com/hertz-contrib/sessions"
    "github.com/hertz-contrib/sessions/cookie"

)

func myErrFunc(c context.Context, ctx *app.RequestContext) {
    if ctx.Errors.Last() == nil {
        fmt.Errorf("myErrFunc called when no error occurs")
    }
    ctx.AbortWithMsg(ctx.Errors.Last().Error(), http.StatusBadRequest)
}

func main() {
    h := server.Default()

    store := cookie.NewStore([]byte("store"))
    h.Use(sessions.New("csrf-session", store))
    h.Use(csrf.New(csrf.WithErrorFunc(myErrFunc)))

    h.GET("/protected", func(c context.Context, ctx *app.RequestContext) {
        ctx.String(200, csrf.GetToken(ctx))
    })
    h.POST("/protected", func(c context.Context, ctx *app.RequestContext) {
        ctx.String(200, "CSRF token is valid")
    })

    h.Spin()
}

The middleware provides WithErrorFunc to facilitate user-defined error handling logic. This configuration can be used when users need to have their own error handling logic. When an error occurs after configuration, it will enter the logic of its own configuration.

WithKeyLookup

package main

import (
    "context"

    "github.com/cloudwego/hertz/pkg/app"
    "github.com/cloudwego/hertz/pkg/app/server"
    "github.com/hertz-contrib/csrf"
    "github.com/hertz-contrib/sessions"
    "github.com/hertz-contrib/sessions/cookie"
)

func main() {
    h := server.Default()

    store := cookie.NewStore([]byte("store"))
    h.Use(sessions.New("csrf-session", store))
    h.Use(csrf.New(csrf.WithKeyLookUp("form：csrf")))

    h.GET("/protected", func(c context.Context, ctx *app.RequestContext) {
        ctx.String(200, csrf.GetToken(ctx))
    })
    h.POST("/protected", func(c context.Context, ctx *app.RequestContext) {
        ctx.String(200, "CSRF token is valid")
    })

    h.Spin()
}

CSRF middleware provides WithKeyLookUp to help users set keyLookup. The middleware will extract the token from the source (supported sources include header, param, query, form). The format is <source>:<key>, and the default value is header:X-CSRF-TOKEN.

WithNext

package main

import (
    "context"

    "github.com/cloudwego/hertz/pkg/app"
    "github.com/cloudwego/hertz/pkg/app/server"
    "github.com/hertz-contrib/csrf"
    "github.com/hertz-contrib/sessions"
    "github.com/hertz-contrib/sessions/cookie"
)

func isPostMethod(_ context.Context, ctx *app.RequestContext) bool {
    if string(ctx.Method()) == "POST" {
        return true
    } else {
        return false
    }
}

func main() {
    h := server.Default()

    store := cookie.NewStore([]byte("store"))
    h.Use(sessions.New("csrf-session", store))

    //  skip csrf middleware when request method is post
    h.Use(csrf.New(csrf.WithNext(isPostMethod)))

    h.POST("/protected", func(c context.Context, ctx *app.RequestContext) {
        ctx.String(200, "success even no csrf-token in header")
    })
    h.Spin()
}

When using this configuration, the use of this middleware can be skipped under certain conditions set by the user.

WithExtractor

package main

import (
    "context"
    "errors"

    "github.com/cloudwego/hertz/pkg/app"
    "github.com/cloudwego/hertz/pkg/app/server"
    "github.com/hertz-contrib/csrf"
    "github.com/hertz-contrib/sessions"
    "github.com/hertz-contrib/sessions/cookie"
)

func myExtractor(c context.Context, ctx *app.RequestContext) (string, error) {
    token ：= ctx.FormValue("csrf-token")
    if token == nil {
        return "", errors.New("missing token in form-data")
    }
    return string(token), nil
}

func main() {
    h := server.Default()

    store := cookie.NewStore([]byte("secret"))
    h.Use(sessions.New("csrf-session", store))
    h.Use(csrf.New(csrf.WithExtractor(myExtractor)))

    h.GET("/protected", func(c context.Context, ctx *app.RequestContext) {
        ctx.String(200, csrf.GetToken(ctx))
    })
    h.POST("/protected", func(c context.Context, ctx *app.RequestContext) {
        ctx.String(200, "CSRF token is valid")
    })

    h.Spin()
}

The default Extractor is obtained through KeyLookup, if the user wants to configure other logic is also supported.

Notes

This intermediate price needs to be used with sessions middleware, and the underlying logic implementation is highly dependent on sessions.

Reference

Golang Reverse Proxy Practices

L2ncE — Fri, 25 Nov 2022 10:29:29 +0000

Hertz

Hertz is an ultra-large-scale enterprise-level microservice HTTP framework, featuring high ease of use, easy expansion, and low latency etc.

Hertz uses the self-developed high-performance network library Netpoll by default. In some special scenarios, Hertz has certain advantages in QPS and latency compared to go net.

In internal practice, some typical services, such as services with a high proportion of frameworks, gateways and other services, after migrating to Hertz, compared to the Gin framework, the resource usage is significantly reduced, CPU usage is reduced by 30%-60% with the size of the traffic.

For more details, see cloudwego/hertz.

Reverse proxy

In computer networks, a reverse proxy is an application that sits in front of back-end applications and forwards client (e.g. browser) requests to those applications.

Reverse proxies help increase scalability, performance, resilience and security. The resources returned to the client appear as if they originated from the web server itself.

Using reverse proxy in Hertz

Using a reverse proxy with Hertz requires pulling the reverseproxy extension provided by the community.

$ go get github.com/hertz-contrib/reverseproxy

Basic using

package main

import (
        "context"

        "github.com/cloudwego/hertz/pkg/app"
        "github.com/cloudwego/hertz/pkg/app/server"
        "github.com/cloudwego/hertz/pkg/common/utils"
        "github.com/hertz-contrib/reverseproxy"
)

func main() {
        h := server.Default(server.WithHostPorts("127.0.0.1:8000"))
        proxy, err := reverseproxy.NewSingleHostReverseProxy("http://127.0.0.1:8000/proxy")
        if err != nil {
                panic(err)
        }
        h.GET("/proxy/backend", func(cc context.Context, c *app.RequestContext) {
                c.JSON(200, utils.H{
                        "msg": "proxy success!!",
                })
        })
        h.GET("/backend", proxy.ServeHTTP)
        h.Spin()
}

We set the target path of the reverse proxy /proxy through the NewSingleHostReverseProxy function. Next, the path of the registered route is the sub-path /proxy/backend of the target path of the reverse proxy, and finally the reverse proxy service proxy.ServeHTTP is mapped by registering /backend. In this way, when we access /backend through the GET method, we will access the content in /proxy/backend.

curl 127.0.0.1:8000/backend

{"msg":"proxy success!!"}

Custom configuration

Of course, the extension is not only able to implement a simple reverse proxy, there are many customizable options provided in the reverseproxy extension.

Method	Description
`SetDirector`	use to customize protocol.Request
`SetClient`	use to customize client
`SetModifyResponse`	use to customize modify response function
`SetErrorHandler`	use to customize error handler

SetDirector & SetClient

We practice using SetDirector and SetClient by implementing a simple service registration discovery.

Server

package main

import (
        "context"

        "github.com/cloudwego/hertz/pkg/app"
        "github.com/cloudwego/hertz/pkg/app/server"
        "github.com/cloudwego/hertz/pkg/app/server/registry"
        "github.com/cloudwego/hertz/pkg/common/utils"
        "github.com/cloudwego/hertz/pkg/protocol/consts"
        "github.com/hertz-contrib/registry/nacos"
)

func main() {
        addr := "127.0.0.1:8000"
        r, _ := nacos.NewDefaultNacosRegistry()
        h := server.Default(
                server.WithHostPorts(addr),
                server.WithRegistry(r, &registry.Info{
                        ServiceName: "demo.hertz-contrib.reverseproxy",
                        Addr:        utils.NewNetAddr("tcp", addr),
                        Weight:      10,
                }),
        )
        h.GET("/backend", func(cc context.Context, c *app.RequestContext) {
                c.JSON(consts.StatusOK, utils.H{"ping": "pong"})
        })
        h.Spin()
}

The sample code on the server side in the hertz-contrib/registry extension is used here. Since this is not the main content of this article, it will not be expanded. For more information, you can Go to the registry repository.

Client

package main

import (
        "github.com/cloudwego/hertz/pkg/app/client"
        "github.com/cloudwego/hertz/pkg/app/middlewares/client/sd"
        "github.com/cloudwego/hertz/pkg/app/server"
        "github.com/cloudwego/hertz/pkg/common/config"
        "github.com/cloudwego/hertz/pkg/protocol"
        "github.com/hertz-contrib/registry/nacos"
        "github.com/hertz-contrib/reverseproxy"
)

func main() {
        cli, err := client.NewClient()
        if err != nil {
                panic(err)
        }
        r, err := nacos.NewDefaultNacosResolver()
        if err != nil {
                panic(err)
        }
        cli.Use(sd.Discovery(r))
        h := server.New(server.WithHostPorts(":8741"))
        proxy, _ := reverseproxy.NewSingleHostReverseProxy("http://demo.hertz-contrib.reverseproxy")
        proxy.SetClient(cli)
        proxy.SetDirector(func(req *protocol.Request) {
                req.SetRequestURI(string(reverseproxy.JoinURLPath(req, proxy.Target)))
                req.Header.SetHostBytes(req.URI().Host())
                req.Options().Apply([]config.RequestOption{config.WithSD(true)})
        })
        h.GET("/backend", proxy.ServeHTTP)
        h.Spin()
}

In the Client section we used a reverse proxy for service discovery. First, specify the client using the service discovery middleware as our forwarding client through SetClient, and then use SetDirector to specify our protocol.Request , and configure the use of service discovery in the new Request.

SetModifyResponse & SetErrorHandler

SetModifyResponse and SetErrorHandler respectively set the response from the backend and the handling of errors arriving in the backend. SetModifyResponse is actually modifyResponse in the reverse proxy extension. If the backend returns any response, no matter what the status code is, this method will be called. If the modifyResponse method returns an error, the errorHandler method will be called with the error as an argument.

SetModifyResponse

package main

import (
        "github.com/cloudwego/hertz/pkg/app/server"
        "github.com/cloudwego/hertz/pkg/protocol"
        "github.com/hertz-contrib/reverseproxy"
)

func main() {
        h := server.Default(server.WithHostPorts("127.0.0.1:8000"))
        // modify response
        proxy, _ := reverseproxy.NewSingleHostReverseProxy("http://127.0.0.1:8000/proxy")
        proxy.SetModifyResponse(func(resp *protocol.Response) error {
                resp.SetStatusCode(200)
                resp.SetBodyRaw([]byte("change response success"))
                return nil
        })
        h.GET("/modifyResponse", proxy.ServeHTTP)

        h.Spin()
}

Here, modifyResponse is modified by SetModifyResponse to change the processing content of the response.

Test

curl 127.0.0.1:8000/modifyResponse

change response success

SetErrorHandler

package main

import (
        "context"

        "github.com/cloudwego/hertz/pkg/app"
        "github.com/cloudwego/hertz/pkg/app/server"
        "github.com/cloudwego/hertz/pkg/common/utils"
        "github.com/hertz-contrib/reverseproxy"
)

func main() {
        h := server.Default(server.WithHostPorts("127.0.0.1:8002"))
        proxy, err := reverseproxy.NewSingleHostReverseProxy("http://127.0.0.1:8000/proxy")
        if err != nil {
                panic(err)
        }
        proxy.SetErrorHandler(func(c *app.RequestContext, err error) {
                c.Response.SetStatusCode(404)
                c.String(404, "fake 404 not found")
        })

        h.GET("/proxy/backend", func(cc context.Context, c *app.RequestContext) {
                c.JSON(200, utils.H{
                        "msg": "proxy success!!",
                })
        })
        h.GET("/backend", proxy.ServeHTTP)
        h.Spin()
}

We use SetErrorHandler to specify how to handle errors that arrive in the background. When an error arrives in the background or there is an error from modifyResponse, the specified processing logic will be run.

Test

curl 127.0.0.1:8002/backend

fake 404 not found

Middleware usage

In addition to basic use, Hertz reverse proxy also supports use in middleware.

package main

import (
        "context"
        "github.com/cloudwego/hertz/pkg/app"
        "github.com/cloudwego/hertz/pkg/app/server"
        "github.com/cloudwego/hertz/pkg/common/utils"
        "github.com/hertz-contrib/reverseproxy"
)

func main() {
        r := server.Default(server.WithHostPorts("127.0.0.1:9998"))
        r2 := server.Default(server.WithHostPorts("127.0.0.1:9997"))

        proxy, err := reverseproxy.NewSingleHostReverseProxy("http://127.0.0.1:9997")
        if err != nil {
                panic(err)
        }

        r.Use(func(c context.Context, ctx *app.RequestContext) {
                if ctx.Query("country") == "cn" {
                        proxy.ServeHTTP(c, ctx)
                        ctx.Response.Header.Set("key", "value")
                        ctx.Abort()
                } else {
                        ctx.Next(c)
                }
        })

        r.GET("/backend", func(c context.Context, ctx *app.RequestContext) {
                ctx.JSON(200, utils.H{
                        "message": "pong1",
                })
        })

        r2.GET("/backend", func(c context.Context, ctx *app.RequestContext) {
                ctx.JSON(200, utils.H{
                        "message": "pong2",
                })
        })

        go r.Spin()
        r2.Spin()
}

In this example code, two Hertz instances are initialized first, then NewSingleHostReverseProxy is used to set the reverse proxy target to port 9997, and finally two routes with the same path are registered for the two instances respectively.

Test1

curl 127.0.0.1:9997/backend

{"message":"pong2"}
curl 127.0.0.1:9998/backend

{"message":"pong1"}

The main part of this code is the middleware usage part. We use the middleware through Use. In the middleware logic, when the logic of ctx.Query("country") == "cn" is established, call proxy. ServeHTTP(c, ctx) uses a reverse proxy, and when you request /backend through instance r, it will request the content of the reverse proxy target port 9997.

Test2

curl 127.0.0.1:9998/backend?country=cn

{"message":"pong2"}

Tips

For NewSingleHostReverseProxy function, if no config.ClientOption is passed it will use the default global client.Client instance. When passing config.ClientOption it will initialize a local client.Client instance. Using ReverseProxy.SetClient if there is need for shared customized client.Client instance.
The reverse proxy resets the header of the response, any such modifications before the request is made will be discarded.

Reference

How to implement an elegant service discovery extension in the HTTP framework

L2ncE — Sun, 20 Nov 2022 14:12:37 +0000

Foreword

In the previous article, the implementation of service registration in Hertz has been interpreted. In this article, we will focus on the interpretation of Hertz's service discovery part.

Hertz

Hertz is an ultra-large-scale enterprise-level microservice HTTP framework, featuring high ease of use, easy expansion, and low latency etc.

Hertz uses the self-developed high-performance network library Netpoll by default. In some special scenarios, Hertz has certain advantages in QPS and latency compared to go net.

In internal practice, some typical services, such as services with a high proportion of frameworks, gateways and other services, after migrating Hertz, compared to the Gin framework, the resource usage is significantly reduced, CPU usage is reduced by 30%-60% with the size of the traffic.

For more details, see cloudwego/hertz.

Service discovery extension

Hertz supports custom discovery modules. Users can extend and integrate other registries by themselves. The extension is defined under pkg/app/client/discovery.

Expansion interface

Service discovery interface definition and implementation

There are three methods in the service discovery interface.

Resolve as the core method of Resolve, it will get the service discovery result we need from the target key.
Target resolves the unique target that Resolve needs to use from the peer TargetInfo provided by Hertz, and this target will be used as the unique key of the cache.
Name is used to specify the unique name of the Resolver, and Hertz will use it to cache and reuse the Resolver.

type Resolver interface {
    // Target should return a description for the given target that is suitable for being a key for cache.
    Target(ctx context.Context, target *TargetInfo) string

    // Resolve returns a list of instances for the given description of a target.
    Resolve(ctx context.Context, desc string) (Result, error)

    // Name returns the name of the resolver.
    Name() string
}

These three methods are implemented in subsequent code in discovery.go.

// SynthesizedResolver synthesizes a Resolver using a resolve function.
type SynthesizedResolver struct {
    TargetFunc  func(ctx context.Context, target *TargetInfo) string
    ResolveFunc func(ctx context.Context, key string) (Result, error)
    NameFunc    func() string
}

func (sr SynthesizedResolver) Target(ctx context.Context, target *TargetInfo) string {
    if sr.TargetFunc == nil {
        return ""
    }
    return sr.TargetFunc(ctx, target)
}

func (sr SynthesizedResolver) Resolve(ctx context.Context, key string) (Result, error) {
    return sr.ResolveFunc(ctx, key)
}

// Name implements the Resolver interface
func (sr SynthesizedResolver) Name() string {
    if sr.NameFunc == nil {
        return ""
    }
    return sr.NameFunc()
}

There are three resolution functions in SynthesizedResolver here for each of the three implementations to resolve.

TargetInfo definition

As mentioned above, the Target method resolves the only target that Resolve needs to use from TargetInfo.

type TargetInfo struct {
    Host string
    Tags map[string]string
}

instance interface definition and implementation

Instance contains information from the target service instance. There are three methods.

Address is the address of the target service.
Weight serves the weight of the target.
Tag is the tag for the target service, in the form of key-value pairs.

// Instance contains information of an instance from the target service.
type Instance interface {
    Address() net.Addr
    Weight() int
    Tag(key string) (value string, exist bool)
}

These three methods are implemented in subsequent code in discovery.go.

type instance struct {
    addr   net.Addr
    weight int
    tags   map[string]string
}

func (i *instance) Address() net.Addr {
    return i.addr
}

func (i *instance) Weight() int {
    if i.weight > 0 {
        return i.weight
    }
    return registry.DefaultWeight
}

func (i *instance) Tag(key string) (value string, exist bool) {
    value, exist = i.tags[key]
    return
}

NewInstance

NewInstance creates an instance with the given network, address and tags.

// NewInstance creates an Instance using the given network, address and tags
func NewInstance(network, address string, weight int, tags map[string]string) Instance {
    return &instance{
        addr:   utils.NewNetAddr(network, address),
        weight: weight,
        tags:   tags,
    }
}

Result

As mentioned above, the Resolve method will get the service discovery result we need from the target key. Result contains the results from service discovery. The instance list is cached and can be mapped to the cache using the CacheKey.

// Result contains the result of service discovery process.
// the instance list can/should be cached and CacheKey can be used to map the instance list in cache.
type Result struct {
    CacheKey  string
    Instances []Instance
}

client middleware

Client middleware is defined under pkg/app/client/middlewares/client.

Discovery

Discovery will use the BalancerFactory to construct a middleware. First read and apply the configuration we passed in through the Apply method. The detailed configuration information is defined under pkg/app/client/middlewares/client/sd/options.go. Then assign the service discovery center, load balancer and load balancing configuration we set to lbConfig, call NewBalancerFactory to pass in lbConfig, and finally return an anonymous function of type client.Middleware.

// Discovery will construct a middleware with BalancerFactory.
func Discovery(resolver discovery.Resolver, opts ...ServiceDiscoveryOption) client.Middleware {
    options := &ServiceDiscoveryOptions{
        Balancer: loadbalance.NewWeightedBalancer(),
        LbOpts:   loadbalance.DefaultLbOpts,
        Resolver: resolver,
    }
    options.Apply(opts)

    lbConfig := loadbalance.Config{
        Resolver: options.Resolver,
        Balancer: options.Balancer,
        LbOpts:   options.LbOpts,
    }

    f := loadbalance.NewBalancerFactory(lbConfig)
    return func(next client.Endpoint) client.Endpoint {
        // ...
    }
}

Implementation principle

The implementation principle of service discovery middleware is actually the last part of Discovery that we did not parse above. We will reset the Host in the middleware. When the configuration in the request is not empty and IsSD() is configured as True, we get an instance and call SetHost to reset the Host.

return func(ctx context.Context, req *protocol.Request, resp *protocol.Response) (err error) {
  if req.Options() != nil && req.Options().IsSD() {
    ins, err := f.GetInstance(ctx, req)
    if err != nil {
      return err
    }
    req.SetHost(ins.Address().String())
  }
  return next(ctx, req, resp)
}

Implementation analysis of service discovery

Regular refresh

In practice, our service discovery information is updated frequently. Hertz uses the refresh method to periodically refresh our service discovery information. We will refresh through a for range loop, where the interval between the loops is the RefreshInterval in the configuration. Then we refresh by traversing the key-value pairs in the cache through the Range method in the sync library function.

// refresh is used to update service discovery information periodically.
func (b *BalancerFactory) refresh() {
    for range time.Tick(b.opts.RefreshInterval) {
        b.cache.Range(func(key, value interface{}) bool {
            res, err := b.resolver.Resolve(context.Background(), key.(string))
            if err != nil {
                hlog.SystemLogger().Warnf("resolver refresh failed, key=%s error=%s", key, err.Error())
                return true
            }
            renameResultCacheKey(&res, b.resolver.Name())
            cache := value.(*cacheResult)
            cache.res.Store(res)
            atomic.StoreInt32(&cache.expire, 0)
            b.balancer.Rebalance(res)
            return true
        })
    }
}

resolver cache

In the comments of NewBalancerFactory, we can know that when we get the same key as the target in the cache, we will get and reuse this load balancer from the cache. Let's briefly analyze its implementation. We pass the service discovery center, load balancer and load balancing configuration together into the cacheKey function to get the uniqueKey .

func cacheKey(resolver, balancer string, opts Options) string {
    return fmt.Sprintf("%s|%s|{%s %s}", resolver, balancer, opts.RefreshInterval, opts.ExpireInterval)
}

Then we will use the Load method to find out whether there is the same uniqueKey in the map, if so, we will directly return to the load balancer. If not, we will add it to the cache.

func NewBalancerFactory(config Config) *BalancerFactory {
    config.LbOpts.Check()
    uniqueKey := cacheKey(config.Resolver.Name(), config.Balancer.Name(), config.LbOpts)
    val, ok := balancerFactories.Load(uniqueKey)
    if ok {
        return val.(*BalancerFactory)
    }
    val, _, _ = balancerFactoriesSfg.Do(uniqueKey, func() (interface{}, error) {
        b := &BalancerFactory{
            opts:     config.LbOpts,
            resolver: config.Resolver,
            balancer: config.Balancer,
        }
        go b.watcher()
        go b.refresh()
        balancerFactories.Store(uniqueKey, b)
        return b, nil
    })
    return val.(*BalancerFactory)
}

There will be a problem if there is no cache for reuse. When the middleware initializes and executes two coroutines, if the user creates a new client every time, it will cause the coroutine to leak.

Summarize

In this article, we learned about the interface definition of Hertz service discovery, the design of client middleware, and the reason and implementation of using timed refresh and cache in service discovery implementation.

Finally, if the article is helpful to you, please like and share it, this is the greatest encouragement to me!

Reference

cloudwego/hertz

Interpretation of Open Source Go HTTP Framework | Service Registration Extension Implementation

L2ncE — Sun, 13 Nov 2022 07:51:01 +0000

Foreword

During the development iterations of the Hertz framework, I became more and more familiar with Hertz's main library. In the next few articles, I will analyze Hertz's service registration, service discovery and load balancing expansion respectively, and finally use the etcd expansion adapted to Hertz for actual combat. Welcome everyone to pay attention.

Hertz

Hertz is an ultra-large-scale enterprise-level microservice HTTP framework, featuring high ease of use, easy expansion, and low latency etc.

Hertz uses the self-developed high-performance network library Netpoll by default. In some special scenarios, Hertz has certain advantages in QPS and latency compared to go net.

In internal practice, some typical services, such as services with a high proportion of frameworks, gateways and other services, after migrating Hertz, compared to the Gin framework, the resource usage is significantly reduced, CPU usage is reduced by 30%-60% with the size of the traffic.

For more details, see cloudwego/hertz.

Service registration extension

Hertz supports custom registration modules. Users can extend and integrate other registries by themselves. The extension is defined under pkg/app/server/registry.

Extended interface and Info

Service registration interface definition and implementation

The interface definition of service registration is similar to the interface definition of implementing service registration and the implementation of most service registrations. It contains two methods, one for service registration and the other for service deregistration.

// Registry is extension interface of service registry.
type Registry interface {
        Register(info *Info) error
        Deregister(info *Info) error
}

These two methods are implemented in subsequent code in register.go.

// NoopRegistry
type noopRegistry struct{}

func (e noopRegistry) Register(*Info) error {
        return nil
}

func (e noopRegistry) Deregister(*Info) error {
        return nil
}

An empty Registry implementation is also provided in register.go, the default for service registration in the Hertz configuration.

// NoopRegistry is an empty implement of Registry
var NoopRegistry Registry = &noopRegistry{}

It is also the default value for service registration in Hertz configuration.

func NewOptions(opts []Option) *Options {
    options := &Options{
        // ...
        Registry: registry.NoopRegistry,
    }
    options.Apply(opts)
    return options
}

Registration Info

The definition of registration information is provided in registry.go. When using WithRegistry for configuration service registration, the registration information will be initialized and passed to the Register method for subsequent logic execution. These fields are only suggestions, and the exact usage depends on your design.

// Info is used for registry.
// The fields are just suggested, which is used depends on design.
type Info struct {
        // ServiceName will be set in hertz by default
        ServiceName string
        // Addr will be set in hertz by default
        Addr net.Addr
        // Weight will be set in hertz by default
        Weight int
        // extend other infos with Tags.
        Tags map[string]string
}

Timing of service registration

We run initOnRunHooks every time the Spin method is called, and initOnRunHooks contains the timing of our service registration.

func (h *Hertz) initOnRunHooks(errChan chan error) {
        // add register func to runHooks
        opt := h.GetOptions()
        h.OnRun = append(h.OnRun, func(ctx context.Context) error {
                go func() {
                        // delay register 1s
                        time.Sleep(1 * time.Second)
                        if err := opt.Registry.Register(opt.RegistryInfo); err != nil {
                                hlog.SystemLogger().Errorf("Register error=%v", err)
                                // pass err to errChan
                                errChan <- err
                        }
                }()
                return nil
        })
}

When calling initOnRunHooks, we will add the anonymous function registered by the service to runHooks. In this function, we first start a goroutine. Here we will delay one second through time.Sleep. When asynchronous registration, the service will not necessarily start, so there will be a delay of one second to wait for the service to start. After this call Register and pass in the Info from the configuration. If there is an error during registration, pass the error to errChan.

Timing of service deregistration

When receiving a signal that the program exits, Hertz will perform a graceful exit and call the Shutdown method, in which the service will be unregistered. First execute executeOnShutdownHooks concurrently and wait for them until the wait times out or finishes execution. Then it will check whether there is a registered service, and if so, call Deregister to deregister the service.

func (engine *Engine) Shutdown(ctx context.Context) (err error) {
   if atomic.LoadUint32(&engine.status) != statusRunning {
      return errStatusNotRunning
   }
   if !atomic.CompareAndSwapUint32(&engine.status, statusRunning, statusShutdown) {
      return
   }

   ch := make(chan struct{})
   // trigger hooks if any
   go engine.executeOnShutdownHooks(ctx, ch)

   defer func() {
      // ensure that the hook is executed until wait timeout or finish
      select {
      case <-ctx.Done():
         hlog.SystemLogger().Infof("Execute OnShutdownHooks timeout: error=%v", ctx.Err())
         return
      case <-ch:
         hlog.SystemLogger().Info("Execute OnShutdownHooks finish")
         return
      }
   }()

   if opt := engine.options; opt != nil && opt.Registry != nil {
      if err = opt.Registry.Deregister(opt.RegistryInfo); err != nil {
         hlog.SystemLogger().Errorf("Deregister error=%v", err)
         return err
      }
   }

   // call transport shutdown
   if err := engine.transport.Shutdown(ctx); err != ctx.Err() {
      return err
   }

   return
}

Summary

In this article we learned about Hertz's implementation of highly customizable service registry extensions, and analyzed how Hertz integrates it into the core of the framework.

Finally, if the article is helpful to you, please like and share, thank you!

Reference

cloudwego/hertz

Implementation of the core structure of the high-performance Go HTTP framework Hertz for beginners

L2ncE — Fri, 28 Oct 2022 01:54:18 +0000

Hertz

Hertz is an ultra-large-scale enterprise-level microservice HTTP framework, featuring high ease of use, easy expansion, and low latency etc.

Hertz uses the self-developed high-performance network library Netpoll by default. In some special scenarios, Hertz has certain advantages in QPS and latency compared to go net. For performance data, please refer to the echo data below.

In internal practice, for some typical services, such as services with a high proportion of frameworks, gateways and other services, after migrating Hertz, compared to the Gin framework, the resource usage is significantly reduced. For more information, see hertz-benchmark.

Hertz provides an easy-to-use command line tool Hz. Users only need to provide an IDL. According to the defined interface information, Hz can generate project scaffolding with one click, and use Hertz out of the box; Hz also provides update capabilities. The IDL of Hz can update the scaffolding if it changes. Currently Hz supports both Thrift and Protobuf IDL definitions. The command line tool has built-in rich options that can be used according to your needs. At the same time, it relies on the official Protobuf compiler and the self-developed Thriftgo compiler at the bottom, both of which support custom generated code plugins. If you feel that the default template cannot meet the needs, you can customize the generated template.

For more information, see.

Implementation of the core structure

Hertz

To learn a framework, you must first learn its core structure, and the core structure and entry of the Hertz framework is the file hertz.go with the same name as itself. The document is not lengthy, it can be said to be short and concise.

The core structure is at the beginning of the file with a prominent line of comments.

// Hertz is the core struct of hertz.
type Hertz struct {
   *route.Engine
}

The comment means that the Hertz structure here is the core structure of the entire framework. The structure encapsulates the Engine under route, and the engine contains all the methods. If you want to use this framework, you must rely on this engine.

New

// New creates a hertz instance without any default config.
func New(opts ...config.Option) *Hertz {
   options := config.NewOptions(opts)
   h := &Hertz{
      Engine: route.NewEngine(options),
   }
   return h
}

New is the constructor of the engine. You can create a new Engine instance and it will not contain the default configuration, but you can customize the relevant configuration yourself, and the instance will be returned after construction.

Default

Usually we use Default instead of New directly in our development, because Default will use the default middleware Recovery, and the Gin framework will also have log middleware.

// Default creates a hertz instance with default middlewares.
func Default(opts ...config.Option) *Hertz {
   h := New(opts...)
   h.Use(recovery.Recovery())

   return h
}

When calling the Default function, an instance of Engine will be created first, and the Recovery middleware will be used. The implementation of Recovery is very simple. Use defer to mount the error recovery function, and call recover in this function (), catch panic, and print the stack information in the log, returning Internal Server Error to the user. It is possible to avoid the entire program terminating due to panic.

In addition, Default also supports custom configuration information.

In the code implementation, we will first make a channel and run a goroutine to wait for receiving information. When receiving the closing signal, we will gracefully close the program. And about the waitSignal among them, we will continue to interpret it below.

SetCustomSignalWaiter

SetCustomSignalWaiter sets the signal waiter function. If Default one is not met the requirement, set this function to customize. Hertz will exit immediately if f returns an error, otherwise it will exit gracefully.

func (h *Hertz) SetCustomSignalWaiter(f func(err chan error) error) {
    h.signalWaiter = f
}

waitSignal

In this function, we will wait for the signal and have a select to correspond to the next operation, including forced exit and graceful exit, and err will be returned if there is an error.

func waitSignal(errCh chan error) error {
   signals := make(chan os.Signal, 1)
   signal.Notify(signals, syscall.SIGINT, syscall.SIGHUP, syscall.SIGTERM)

   select {
   case sig := <-signals:
      switch sig {
      case syscall.SIGTERM:
         // force exit
         return errors.New(sig.String()) // nolint
      case syscall.SIGHUP, syscall.SIGINT:
         // graceful shutdown
         return nil
      }
   case err := <-errCh:
      return err
   }

   return nil
}

Summary

After that, we have already read the source code of hertz.go, but there may still be some things that you don't understand if you only see the source code. Next, we will use the example of CloudWeGo to further see how it is used.

Example

Let's look directly at hertz-examples/hello/main.go.

package main

import (
    "context"

    "github.com/cloudwego/hertz/pkg/app"
    "github.com/cloudwego/hertz/pkg/app/server"
    "github.com/cloudwego/hertz/pkg/protocol/consts"
)

func main() {
    // server.Default() creates a Hertz with recovery middleware.
    // If you need a pure hertz, you can use server.New()
    h := server.Default()

    h.GET("/hello", func(ctx context.Context, c *app.RequestContext) {
        c.String(consts.StatusOK, "Hello hertz!")
    })

    h.Spin()
}

Entering the first line of the main function tells that using Default will have its own error recovery middleware. If you want a pure instance, please use New. Next he calls server.Default(), which is followed by a route for a GET request, which prints "Hello hertz!". Finally called Spin(), waiting for the signal.

Summary

You can check out the cloudwego/hertz for more information. I'm sure the documentation has answers to all your questions.