Service/Protocol

You can expose existing services or implement the corresponding protocol yourself to expose services externally

Detailed examples referencehere

Implemented services

• rest

• grpc

• pprof

public configuration

## Service-related configuration
asjard:
  ## Multi-protocol service related configuration
  ## Not effective in real time, restart required after modification
  servers:
    ## Protocol-agnostic server interceptor list, multiple interceptors separated by commas (,)
    # interceptors: ""
    ## Built-in configured interceptors
    # builtInInterceptors:
    #   - ratelimiter
    #   - metrics
    #   - accessLog
    #   - restReadEntity
    #   - restResponseHeader
    #   - i18n
    #   - trace
    ## Default handlers
    # defaultHandlers: ""
    ## Built-in configured default handlers
    # builtInDefaultHandlers:
    #   - health
    #   - metrics
    ## Certificate file path, relative to ASJARD_CERT_DIR
    certFile: ""
    ## Private key file path, relative to ASJARD_CERT_DIR
    keyFile: ""

How to implement your own service

Configuration conventions

• Configurations should all be placed underasjard.servers.{custom service name}Under this namespace

Custom service

For specifics refer tocore/server/server.goin the code

• You need to implement the following two methods

// Server content that each protocol needs to implement
type Server interface {
	// Register
	AddHandler(handler any) error
	// Service start
	Start(startErr chan error) error
	// Service stop
	Stop()
	// The protocol provided by the service
	Protocol() string
	// Service listen address list
	ListenAddresses() AddressConfig
	// Whether it is enabled
	Enabled() bool
}

// NewServerFunc service initialization method
type NewServerFunc func(options *ServerOptions) (Server, error)

• Then viaAddServeradd the service

func init() {
	server.AddServer(Protocol, New)
}

• Refer to the concrete implementationpkg/server/rest,pkg/server/grpc,pkg/server/pprof

Use

• Step one: Write the protobuf definition file, for details please refer toprotobuf

syntax = "proto3";

package api.v1.example.docs;

// The target Go package path for generated code.
option go_package = "protos-repo/example/api/v1/sample";

import "github.com/asjard/protobuf/http.proto";
import "github.com/asjard/protobuf/validate.proto";

// Sample service provides basic greeting operations.
service Sample {
    // SayHello returns a greeting message based on the provided name.
    // It supports multiple HTTP GET entrypoints for compatibility and routing flexibility.
    rpc SayHello(HelloRequest) returns (HelloReply) {
        // Dynamic path mapping (e.g., /helloworld/john)
        option (asjard.api.http) = {
            get : "/helloworld/{name}"
        };
        // Static path mapping for general greetings
        option (asjard.api.http) = {
            get : '/hello'
        };
    }
}

// HelloRequest defines the input payload for the SayHello method.
message HelloRequest {
    // The name of the person to greet.
    // Validation: Must be provided (required) and no longer than 20 characters.
    string name = 1 [ (asjard.api.validate).rules = "required,max=20" ];
}

// HelloReply defines the output payload containing the greeting result.
message HelloReply {
    // The formatted greeting string (e.g., "Hello, name!").
    string message = 1;
}

• Step two: Compile the proto file

protoc --go_out=${GOPATH}/src -I${GOPATH}/src -I example.proto
# If you need to expose a grpc service, compile the files required by grpc
protoc --go-grpc_out=${GOPATH}/src -I${GOPATH}/src -I example.proto
# If you need to expose a rest service, compile the files required by rest, depends on the previous step
protoc --go-rest_out=${GOPATH}/src -I${GOPATH}/src -I example.proto

• Step three: Write the service

package apiv1

import (
	"context"

	pb "protos-repo/example/api/v1/sample"

	"github.com/asjard/asjard/pkg/server/grpc"
	"github.com/asjard/asjard/pkg/server/rest"
)

type SampleAPI struct {
	pb.UnimplementedSampleServer
}

func NewSampleAPI() *SampleAPI {
	return &SampleAPI{}
}

func (api *SampleAPI) Start() error { return nil }
func (api *SampleAPI) Stop()        {}

// GRPC service
func (api *SampleAPI) GrpcServiceDesc() *grpc.ServiceDesc { return &pb.Sample_ServiceDesc }

// HTTP service
func (api *SampleAPI) RestServiceDesc() *rest.ServiceDesc { return &pb.SampleRestServiceDesc }

func (api *SampleAPI) SayHello(ctx context.Context, in *pb.HelloRequest) (*pb.HelloReply, error) {
	return &pb.HelloReply{
		Message: "hello " + in.Name,
	}, nil
}

• The above three steps are the entire process to write and start a service

• For configuration and access details refer togrpc serviceandrest service