github.com/cloudwego/kitex@v0.9.0/pkg/kerrors/bizerrors.go

/*
 * Copyright 2022 CloudWeGo Authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package kerrors

import (
	"errors"
	"fmt"

	"github.com/cloudwego/kitex/pkg/remote/trans/nphttp2/codes"
	"github.com/cloudwego/kitex/pkg/remote/trans/nphttp2/status"
)

/**
 * BizStatusErrorIface is an interface used to define biz errors. Kitex provides the
 * default implementation of this interface, and you can also implement it by yourself.
 * You can create a biz error through NewBizStatusError or NewBizStatusErrorWithExtra
 * and return it in the server handler. You can also convert the err back to
 * BizStatusErrorIface through FromBizStatusError on the client side to obtain information
 * such as error status codes.
 *
 * Here is the code example:
 *
 * Server:
 *	func (h *Handler) Serve(ctx, Request) (Response, error) {
 *		return nil, kerrors.NewBizStatusError(404, "not found")
 *	}
 *	// ...
 *	svr := myservice.NewServer(&Handler{}, server.WithMetaHandler(transmeta.ServerTTHeaderHandler))
 *
 * Client:
 *	cli := myservice.MustNewClient("client", client.WithTransportProtocol(transport.TTHeader),
 * 		client.WithMetaHandler(transmeta.ClientTTHeaderHandler))
 *	resp, err := cli.Serve(ctx, req)
 *	if err != nil {
 *		if bizErr, ok := kerrors.FromBizStatusError(err); ok {
 *			println(bizErr.BizStatusCode())
 *			println(bizErr.BizMessage())
 *			// ....
 *		}
 *	}
 *
 * NOTICE: ClientTTHeaderHandler and ServerTTHeaderHandler must be configured in
 * the MetaHandler of the corresponding client/server if you're using ttheader
 * as transport protocol, otherwise biz error cannot be correctly transmitted to
 * the client.
 * For custom transport protocol, you need to read and write rpcinfo.TransInfo() in
 * your own MetaHandler, and convert it with rpcinfo.Invocation().BizStatusErr().
 * For more details, please refer to the implementation of ClientTTHeaderHandler and
 * ServerTTHeaderHandler.
 */

type BizStatusErrorIface interface {
	BizStatusCode() int32
	BizMessage() string
	BizExtra() map[string]string
	Error() string
}

/**
 * GRPCStatusIface must be implemented by the BizStatusErrorIface implementation also
 * if you need to transmit GRPCStatus.Details in your rpc response.
 * Here is the code example:
 *
 * Server:
 *	func (h *Handler) Serve(ctx, Request) (Response, error) {
 *		bizErr := kerrors.NewGRPCBizStatusError(404, "not found")
 *		grpcStatusErr := bizErr.(kerrors.GRPCStatusIface)
 *		st, _ := grpcStatusErr.GRPCStatus().WithDetails(&echo.Echo{Str: "hello world"})
 *		grpcStatusErr.SetGRPCStatus(st)
 *		return nil, bizErr
 *	}
 *	// ...
 *	svr := myservice.NewServer(&Handler{})
 *
 * Client:
 *	// Replace these two functions to let Kitex pass Details successfully.
 *	cli := myservice.MustNewClient("client", client.WithTransportProtocol(transport.GRPC))
 *	resp, err := cli.Serve(ctx, req)
 *	if err != nil {
 *		if bizErr, ok := kerrors.FromBizStatusError(err); ok {
 *  		println(bizErr.BizStatusCode())
 *			println(bizErr.BizMessage())
 *			println(bizErr.(status.Iface).GRPCStatus().Details()[0].(*echo.Echo).Str)
 *			// ...
 *		}
 *	}
 */

type GRPCStatusIface interface {
	GRPCStatus() *status.Status
	SetGRPCStatus(status *status.Status)
}

type BizStatusError struct {
	code  int32
	msg   string
	extra map[string]string
}

// FromBizStatusError converts err to BizStatusErrorIface.
func FromBizStatusError(err error) (bizErr BizStatusErrorIface, ok bool) {
	if err == nil {
		return
	}
	ok = errors.As(err, &bizErr)
	return
}

// NewBizStatusError returns BizStatusErrorIface by passing in code and msg.
func NewBizStatusError(code int32, msg string) BizStatusErrorIface {
	return &BizStatusError{code: code, msg: msg}
}

// NewBizStatusErrorWithExtra returns BizStatusErrorIface which contains extra info.
func NewBizStatusErrorWithExtra(code int32, msg string, extra map[string]string) BizStatusErrorIface {
	return &BizStatusError{code: code, msg: msg, extra: extra}
}

func (e *BizStatusError) BizStatusCode() int32 {
	return e.code
}

func (e *BizStatusError) BizMessage() string {
	return e.msg
}

func (e *BizStatusError) AppendBizMessage(extraMsg string) {
	if extraMsg != "" {
		e.msg = fmt.Sprintf("%s %s", e.msg, extraMsg)
	}
}

func (e *BizStatusError) BizExtra() map[string]string {
	return e.extra
}

func (e *BizStatusError) SetBizExtra(key, value string) {
	if e.extra == nil {
		e.extra = make(map[string]string)
	}
	e.extra[key] = value
}

func (e *BizStatusError) Error() string {
	return fmt.Sprintf("biz error: code=%d, msg=%s", e.code, e.msg)
}

// NewGRPCBizStatusError returns *GRPCBizStatusError which implements both
// BizStatusErrorIface and GRPCStatusIface, use this function instead of NewBizStatusError
// to pass status.Details in gRPC scenario.
func NewGRPCBizStatusError(code int32, msg string) BizStatusErrorIface {
	return &GRPCBizStatusError{BizStatusError: BizStatusError{code: code, msg: msg}}
}

// NewGRPCBizStatusErrorWithExtra returns *GRPCBizStatusError which implements both
// BizStatusErrorIface and GRPCStatusIface, use this function instead of NewBizStatusErrorWithExtra
// to pass status.Details in gRPC scenario.
func NewGRPCBizStatusErrorWithExtra(code int32, msg string, extra map[string]string) BizStatusErrorIface {
	return &GRPCBizStatusError{BizStatusError: BizStatusError{code: code, msg: msg, extra: extra}}
}

type GRPCBizStatusError struct {
	BizStatusError

	// for grpc
	status *status.Status
}

func (e *GRPCBizStatusError) GRPCStatus() *status.Status {
	if e.status == nil {
		e.status = status.New(codes.Internal, e.msg)
	}
	return e.status
}

func (e *GRPCBizStatusError) SetGRPCStatus(status *status.Status) {
	e.status = status
}