Merge pull request #49 from DMwangnima/dev-docs

feat: regenerate IDL files and finish docs

.gitignore

@@ -30,3 +30,4 @@ output/*
 
 # Maven generated files
 /tests/dubbo-java/target/
+/samples/helloworld/dubbo/target

.licenserc.yaml

@@ -71,6 +71,7 @@ header: # `header` section is configurations for source codes license header.
     - 'LICENSE-APACHE'
     - 'OWNERS'
     - 'tests'
+    - 'samples'
   comment: on-failure # on what condition license-eye will comment on the pull request, `on-failure`, `always`, `never`.
 
   language:

README.md

@@ -3,18 +3,246 @@
 
 ---
 
-> **Notice: When decoding, the java version of hessian will default skip and ignore non-exist fields.**
 
-
-It's a golang dubbo library used by kitex (https://github.com/cloudwego/kitex).
+Golang dubbo library used by kitex (https://github.com/cloudwego/kitex) for **kitex-dubbo interoperability**.
 
 
 ## Feature List
 
+### Type Mapping
+
+|    thrift type     |   golang type    | hessian2 type |       java type        |
+|:------------------:|:----------------:|:-------------:|:----------------------:|
+|        bool        |       bool       |    boolean    |   java.lang.Boolean    |
+|        byte        |       int8       |      int      |     java.lang.Byte     |
+|        i16         |      int16       |      int      |    java.lang.Short     |
+|        i32         |      int32       |      int      |   java.lang.Integer    |
+|        i64         |      int64       |     long      |     java.lang.Long     |
+|       double       |     float64      |    double     |    java.lang.Double    |
+|       string       |      string      |    string     |    java.lang.String    |
+|       binary       |      []byte      |    binary     |         byte[]         |
+|    list\<bool>     |      []bool      |     list      |     List\<Boolean>     |
+|     list\<i32>     |     []int32      |     list      |     List\<Integer>     |
+|     list\<i64>     |     []int64      |     list      |      List\<Long>       |
+|   list\<double>    |    []float64     |     list      |     List\<Double>      |
+|   list\<string>    |     []string     |     list      |     List\<String>      |
+|  map\<bool, bool>  |  map[bool]bool   |      map      | Map\<Boolean, Boolean> |
+|  map\<bool, i32>   |  map[bool]int32  |      map      | Map\<Boolean, Integer> |
+|  map\<bool, i64>   |  map[bool]int64  |      map      |  Map\<Boolean, Long>   |
+| map\<bool, double> | map[bool]float64 |      map      | Map\<Boolean, Double>  |
+| map\<bool, string> | map[bool]string  |      map      | Map\<Boolean, String>  |
+
+**Important notes**:
+1. The list of map types is not exhaustive and includes only tested cases.
+Please do not use keys and values with **i8**, **i16** and **binary**.
+2. Currently only the thrift type and java type mappings documented in the table are supported.
+More mappings(e.g. **bool** <-> **boolean**) would be supported in the future.
+Please see [issue](https://github.com/kitex-contrib/codec-dubbo/issues/46).
+3. float32 is not supported by thrift.
+
+### Kitex-Dubbo Interoperability
+
+1. **kitex -> dubbo**  
+Write **api.thrift** based on existing **dubbo Interface API** and [**Type Mapping Table**](#type-mapping). Then use
+latest kitex command tool and thriftgo to generate stub code.
+2. **dubbo -> kitex**  
+Write dubbo client code based on existing **api.thrift** and [**Type Mapping Table**](#type-mapping).
+
+## Getting Started
+
+[**Concrete sample**](https://github.com/kitex-contrib/codec-dubbo/tree/main/samples//helloworld/).
+
+### Prerequisites
+
+```shell
+# install kitex cmd tool
+go install github.com/cloudwego/kitex/tool/cmd/kitex@008f748
+
+# install thriftgo
+go install github.com/cloudwego/thriftgo@latest
+```
+
+### Generating kitex stub codes
+
+```shell
+mkdir ~/kitex-dubbo-demo && cd ~/kitex-dubbo-demo
+go mod init kitex-dubbo-demo
+cat > api.thrift << EOF
+namespace go hello
+
+struct GreetRequest {
+    1: required string req,
+}(JavaClassName="org.cloudwego.kitex.samples.api.GreetRequest")
+
+struct GreetResponse {
+    1: required string resp,
+}(JavaClassName="org.cloudwego.kitex.samples.api.GreetResponse")
+
+service GreetService {
+    string Greet(1: string req)
+    GreetResponse GreetWithStruct(1: GreetRequest req)
+}
+
+EOF
+kitex -module kitex-dubbo-demo -thrift template=slim -service GreetService -protocol Hessian2 ./api.thrift
+```
+
+Important Notes:
+1. JavaClassName of struct in **api.thrift** must be consistent with the target one.
+
+### Finishing business logic and configuration
+
+#### business logic
+
+```go
+import (
+    "context"
+    hello "github.com/kitex-contrib/codec-dubbo/samples/helloworld/kitex/kitex_gen/hello"
+)
+
+// implement interface in handler.go
+func (s *GreetServiceImpl) Greet(ctx context.Context, req string) (resp string, err error) {
+	return "Hello " + req, nil
+}
+
+func (s *GreetServiceImpl) GreetWithStruct(ctx context.Context, req *hello.GreetRequest) (resp *hello.GreetResponse, err error) {
+	return &hello.GreetResponse{Resp: "Hello " + req.Req}, nil
+}
+```
+
+Implement interface in **handler.go**.
+
+#### initializing client
+
+```go
+import (
+	"context"
+	"github.com/cloudwego/kitex/client"
+	"github.com/cloudwego/kitex/pkg/klog"
+	dubbo "github.com/kitex-contrib/codec-dubbo/pkg"  
+	"github.com/kitex-contrib/codec-dubbo/samples/helloworld/kitex/kitex_gen/hello"
+	"github.com/kitex-contrib/codec-dubbo/samples/helloworld/kitex/kitex_gen/hello/greetservice"
+)
+
+func main() {
+	cli, err := greetservice.NewClient("helloworld",
+		// specify address of target server
+		client.WithHostPorts("127.0.0.1:21001"),
+		// configure dubbo codec
+		client.WithCodec(
+			dubbo.NewDubboCodec(
+				// target dubbo Interface Name
+				dubbo.WithJavaClassName("org.cloudwego.kitex.samples.api.GreetProvider"),
+			),
+		),
+	)
+	if err != nil {
+		panic(err)
+	}
+
+	resp, err := cli.Greet(context.Background(), "world")
+	if err != nil {
+		klog.Error(err)
+		return
+	}
+	klog.Infof("resp: %s", resp)
+
+	respWithStruct, err := cli.GreetWithStruct(context.Background(), &hello.GreetRequest{Req: "world"})
+	if err != nil {
+		klog.Error(err)
+		return
+	}
+	klog.Infof("respWithStruct: %s", respWithStruct.Resp)
+}
+```
+
+Important notes:
+1. Each dubbo Interface corresponds to a DubboCodec. Please do not configure multiple clients sharing a single DubboCodec.
+
+#### initializing server
+
+```go
+import (
+	"github.com/cloudwego/kitex/server"
+	dubbo "github.com/kitex-contrib/codec-dubbo/pkg"
+	hello "github.com/kitex-contrib/codec-dubbo/samples/helloworld/kitex/kitex_gen/hello/greetservice"
+	"log"
+	"net"
+)
+
+func main() {
+	// server address to listen on
+	addr, _ := net.ResolveTCPAddr("tcp", ":21000")
+	svr := hello.NewServer(new(GreetServiceImpl),
+		server.WithServiceAddr(addr),
+		// configure DubboCodec
+		server.WithCodec(dubbo.NewDubboCodec(
+			// Interface Name of kitex service. Other dubbo clients and kitex clients can refer to this name for invocation.
+			dubbo.WithJavaClassName("org.cloudwego.kitex.samples.api.GreetProvider"),
+		)),
+	)
+
+	err := svr.Run()
+
+	if err != nil {
+		log.Println(err.Error())
+	}
+}
+```
+
+Important notes:
+1. Each Interface Name corresponds to a DubboCodec. Please do not configure multiple servers sharing a single DubboCodec.
+
+## Benchmark
+
+### Benchmark Environment 
+CPU: **Intel(R) Xeon(R) Gold 5118 CPU @ 2.30GHz**  
+Memory: **192GB**
+
+### Benchmark Code
+
+Referring to [dubbo-go-benchmark](https://github.com/dubbogo/dubbo-go-benchmark). Converting dubbo client and dubbo server
+to kitex client and kitex server. Please see [this](https://github.com/kitex-contrib/codec-dubbo/tree/main/tests/benchmark).
+
+### Benchmark Result
+
+#### kitex -> kitex
+
+```shell
+bash deploy.sh kitex_server -p 21001
+bash deploy.sh kitex_client -p 21002 -addr "127.0.0.1:21001"
+bash deploy.sh stress -addr '127.0.0.1:21002' -t 1000000 -p 100 -l 256
+```
+
+Result:
+
+| average rt |  tps  | success rate |
+|:----------:|:-----:|:------------:|
+|  2310628   | 46015 |   1.000000   |
+|  2363729   | 44202 |   1.000000   |
+|  2256177   | 43280 |   1.000000   |
+|  2194147   | 43171 |   1.000000   |
+
+Resource:
+
+|   process_name    | %CPU  | %MEM |
+|:-----------------:|:-----:|:----:|
+| kitex_client_main | 914.6 | 0.0  |
+| kitex_server_main | 520.5 | 0.0  |
+|    stress_main    | 1029  | 0.1  |
+
+### Benchmark Summary
+
+Since the [**dubbo-go-hessian2**](https://github.com/apache/dubbo-go-hessian2) relies on reflect to encoding/decoding, 
+there's great potential to improve the performance with a codec based on generated Go code. 
+A fastCodec for Hessian2 (#46) is planned for better performance.
 
+## Acknowledgements
 
-## reference
+We extend our sincere appreciation to the dubbo-go development team for their valuable contribution!
+- [**dubbo-go**](https://github.com/apache/dubbo-go)
+- [**dubbo-go-hessian2**](https://github.com/apache/dubbo-go-hessian2)
 
-- [hessian serialization](http://hessian.caucho.com/doc/hessian-serialization.html)
+## Reference
 
-## Basic Usage Examples
+- [hessian serialization](http://hessian.caucho.com/doc/hessian-serialization.html)

samples/helloworld/dubbo/README.md

@@ -0,0 +1,17 @@
+# About this directory
+
+This code is used for kitex-dubbo interoperability samples.
+
+## Start the service consumer
+
+```bash
+mvn clean package
+mvn -Djava.net.preferIPv4Stack=true -Dexec.mainClass=org.cloudwego.kitex.samples.client.Application exec:java
+```
+
+## Start the service provider
+
+```bash
+mvn clean package
+mvn -Djava.net.preferIPv4Stack=true -Dexec.mainClass=org.cloudwego.kitex.samples.provider.Application exec:java
+```

samples/helloworld/dubbo/pom.xml

@@ -0,0 +1,90 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+  ~ Licensed to the Apache Software Foundation (ASF) under one or more
+  ~ contributor license agreements.  See the NOTICE file distributed with
+  ~ this work for additional information regarding copyright ownership.
+  ~ The ASF licenses this file to You 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.
+  -->
+
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <parent>
+        <groupId>org.apache</groupId>
+        <artifactId>apache</artifactId>
+        <version>23</version>
+        <relativePath/>
+    </parent>
+
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <version>3.8.1</version>
+                <configuration>
+                    <source>8</source>
+                    <target>8</target>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
+
+    <groupId>org.cloudwego.kitex</groupId>
+    <version>1.0-SNAPSHOT</version>
+
+    <modelVersion>4.0.0</modelVersion>
+
+    <artifactId>kitex-samples</artifactId>
+    <name>Kitex Samples</name>
+    <description>Kitex Samples</description>
+
+    <properties>
+        <dubbo.version>3.2.0</dubbo.version>
+        <junit5.version>5.9.2</junit5.version>
+    </properties>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.apache.dubbo</groupId>
+            <artifactId>dubbo</artifactId>
+            <version>${dubbo.version}</version>
+        </dependency>
+
+        <dependency>
+            <groupId>org.apache.dubbo</groupId>
+            <artifactId>dubbo-dependencies-zookeeper-curator5</artifactId>
+            <version>${dubbo.version}</version>
+            <type>pom</type>
+        </dependency>
+
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-engine</artifactId>
+            <version>${junit5.version}</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-api</artifactId>
+            <version>${junit5.version}</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.junit.jupiter</groupId>
+            <artifactId>junit-jupiter-params</artifactId>
+            <version>${junit5.version}</version>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+</project>