goes

README

English | 中文

tRPC-Go ElasticSearch Plugin

wrapping community es, used with trpc.

Usage Example

YAML Configuration

All configuration options are placed within the plugins section, with only the service name retained in the client configuration.

client:                                          
  timeout: 1000                                  
  namespace: Development                         
  service:                                         
    - name: trpc.app.service.es

plugins:                                          
  database:
    goes:
      clientoptions:
        - name: trpc.app.service.es # Match the service name in the client configuration
          url: http://127.0.0.1:9200 # Elasticsearch address
          user: username # Username
          password: password # Password
          timeout: 1000 # Timeout
          log:
            enabled: true # Enable logging
            request_enabled: true # Print request logs
            response_enabled: true # Print response logs

API Invocation

goes supports both Elastic V7 and V8 API versions, and no longer supports V6 API version. The SDK supports three calling methods; details can be found in the code usage examples.

Calling through Client.Method

Example for Elastic V7

package main

import (
	"bytes"
	"context"
	"encoding/json"
	"net/http"
	"strconv"

	"trpc.group/trpc-go/trpc-database/goes"
	"github.com/elastic/go-elasticsearch/esapi"

	pb "trpc.test.helloworld"
)

var body = map[string]interface{}{
	"account_number": 111111,
	"firstname":      "User",
	"city":           "Shenzhen",
}

func (s *greeterImpl) SayHello(ctx context.Context, req *pb.HelloRequest) (rsp *pb.HelloReply, err error) {
	// Use es v7 API to execute the request
	proxyV7, err := goes.NewElasticClientV7("trpc.app.service.es")
	if err != nil {
		return nil, err
	}
	jsonBody, err := json.Marshal(body)
	if err != nil {
		return nil, err
	}
	_, err = proxyV7.Index("bank", bytes.NewBuffer(jsonBody), proxyV7.Index.WithContext(ctx))
	if err != nil {
		return nil, err
	}
	return &pb.HelloReply{}, nil
}

Example for Elastic V8

package main

func (s *greeterImpl) SayHello(ctx context.Context, req *pb.HelloRequest) (rsp *pb.HelloReply, err error) {
	// Use es v8 API to execute the request
	proxyV8, err := goes.NewElasticClientV8("trpc.app.service.es")
    if err != nil {
        return nil, err
    }
    jsonBody, err = json.Marshal(body)
	if err != nil {
        return nil, err
    }
    _, err = proxyV8.Index("bank", bytes.NewBuffer(jsonBody), proxyV8.Index.WithContext(ctx))
	if err != nil {
        return nil, err
    }
	
    return &pb.HelloReply{}, nil
}

Calling through MethodRequest.Do

Example for Elastic V7

package main

func (s *greeterImpl) SayHello(ctx context.Context, req *pb.HelloRequest) (rsp *pb.HelloReply, err error) {
	// Use es v7 API to execute the request 
	proxyV7, err := goes.NewElasticClientV7("trpc.app.service.es")
    if err != nil {
        return nil, err
    }
	
    // Build request using es API
    indexRequest := esapi.IndexRequest{
        Index:      "bank", 
        DocumentID: strconv.Itoa(1),
        Body:       bytes.NewReader(jsonBody),
    }
	
    // Execute request using trpc goes client
    _, err = indexRequest.Do(ctx, proxyV7)
    if err != nil {
        return nil, err
    }
    return &pb.HelloReply{}, nil
}

Example for Elastic V8

package main

func (s *greeterImpl) SayHello(ctx context.Context, req *pb.HelloRequest) (rsp *pb.HelloReply, err error) { 
    // Use es v8 API to execute the request
    proxyV8, err := goes.NewElasticClientV8("trpc.app.service.es")
    if err != nil {
        return nil, err
    }
    
    // Build request using es API 
    indexRequestV8 := esapi.IndexRequest{
        Index:      "bank", 
        DocumentID: strconv.Itoa(1), 
        Body:       bytes.NewReader(jsonBody),
    }
    
    // Execute request using trpc goes client
    _, err = indexRequestV8.Do(ctx, proxyV8)
    if err != nil {
        return nil, err
    }
    return &pb.HelloReply{}, nil
}

Calling through RoundTriper.RoundTrip

This method should only be used when fully customizing the es HTTP request is necessary, and in most cases, it is preferable to use the es API for the call.

package main

func (s *greeterImpl) SayHello(ctx context.Context, req *pb.HelloRequest) (rsp *pb.HelloReply, err error) {
    url := &url.URL{Path: "/", Scheme: "http"}
    proxy := goes.NewClientProxy("trpc.app.service.es")
    _, err = proxy.RoundTrip(&http.Request{Method: "GET", Proto: "HTTP/1.1",URL:url, ProtoMajor: 1, ProtoMinor: 1})
    if err != nil {
        return nil, err
    }
    return &pb.HelloReply{}, nil
}

Frequently Asked Questions

1. Both NewElasticClientV7 and NewElasticClientV8 methods create a new connection and send a GET request to the es server to verify server information. It is recommended to reuse the same client to achieve connection reuse.

Documentation

Index

• Variables
• func NewClientTransport(opt ...OptClientTransport) transport.ClientTransport
• func NewElasticClientV7(serviceName string, opts ...client.Option) (*elasticv7.Client, error)
• func NewElasticClientV8(serviceName string, opts ...client.Option) (*elasticv8.Client, error)
• func NewElasticTypedClientV8(serviceName string, opts ...client.Option) (*elasticv8.TypedClient, error)
• type ClientCodec
  • func (c *ClientCodec) Decode(msg codec.Msg, _ []byte) ([]byte, error)
  • func (c *ClientCodec) Encode(msg codec.Msg, _ []byte) ([]byte, error)
• type ClientOption
• type ClientTransport
  • func (ct *ClientTransport) RoundTrip(ctx context.Context, _ []byte, callOpts ...transport.RoundTripOption) ([]byte, error)
• type Config
• type LogConfig
• type OptClientTransport
  • func WithHTTPRoundTripper(rt http.RoundTripper) OptClientTransport
• type Plugin
  • func (m *Plugin) Setup(name string, configDesc plugin.Decoder) error
  • func (m *Plugin) Type() string
• type RoundTriper
  • func NewClientProxy(name string, opts ...client.Option) RoundTriper

Variables

var (
	// DefaultClientCodec default client codec instance
	DefaultClientCodec = &ClientCodec{}
)

var DefaultClientTransport = NewClientTransport()

DefaultClientTransport default elasticsearch transport instance

Functions

func NewClientTransport

func NewClientTransport(opt ...OptClientTransport) transport.ClientTransport

NewClientTransport create a new transport.ClientTransport

func NewElasticClientV7

func NewElasticClientV7(serviceName string, opts ...client.Option) (*elasticv7.Client, error)

NewElasticClientV7 create a new client

func NewElasticClientV8

func NewElasticClientV8(serviceName string, opts ...client.Option) (*elasticv8.Client, error)

NewElasticClientV8 create a new client

func NewElasticTypedClientV8

func NewElasticTypedClientV8(serviceName string, opts ...client.Option) (*elasticv8.TypedClient, error)

NewElasticTypedClientV8 create a new typed client

Types

type ClientCodec

type ClientCodec struct{}

ClientCodec client codec instance for request encode/decode

func (*ClientCodec) Decode

func (c *ClientCodec) Decode(msg codec.Msg, _ []byte) ([]byte, error)

Decode no need to decode anything

func (*ClientCodec) Encode

func (c *ClientCodec) Encode(msg codec.Msg, _ []byte) ([]byte, error)

Encode no need to encode anything

type ClientOption

type ClientOption struct {
	Name     string    `yaml:"name"`     // name
	URL      string    `yaml:"url"`      // url
	User     string    `yaml:"user"`     // user
	Password string    `yaml:"password"` // password
	Timeout  int       `yaml:"timeout"`  // timeout
	Log      LogConfig `yaml:"log"`      // log
}

ClientOption goes database connection option

type ClientTransport

type ClientTransport struct {
	// contains filtered or unexported fields
}

ClientTransport elasticsearch client transport

func (*ClientTransport) RoundTrip

func (ct *ClientTransport) RoundTrip(ctx context.Context, _ []byte, callOpts ...transport.RoundTripOption) (
	[]byte, error)

RoundTrip impl transport.ClientTransport interface method

type Config

type Config struct {
	ClientsOptions []*ClientOption `yaml:"clientoptions"` // goes database option slice
}

Config goes config struct

type LogConfig

type LogConfig struct {
	Enabled         bool `yaml:"enabled"`          // enable log
	RequestEnabled  bool `yaml:"request_enabled"`  // enable request body
	ResponseEnabled bool `yaml:"response_enabled"` // enable response body
}

LogConfig is log configuration

type OptClientTransport

type OptClientTransport func(ct *ClientTransport)

OptClientTransport client transport option

func WithHTTPRoundTripper

func WithHTTPRoundTripper(rt http.RoundTripper) OptClientTransport

WithHTTPRoundTripper set http round tripper

type Plugin

type Plugin struct{}

Plugin plugin struct

func (*Plugin) Setup

func (m *Plugin) Setup(name string, configDesc plugin.Decoder) error

Setup plugin.Factory interface implementation

func (*Plugin) Type

func (m *Plugin) Type() string

Type plugin.Factory interface implementation

type RoundTriper

type RoundTriper interface {
	// RoundTrip elastic client transport method implementation
	RoundTrip(request *http.Request) (*http.Response, error)
}

RoundTriper es client interface

func NewClientProxy

func NewClientProxy(name string, opts ...client.Option) RoundTriper

NewClientProxy create a new elastic client proxy