From 3efa4d7b6538fa33e6be071d20569c4ebd274c30 Mon Sep 17 00:00:00 2001
From: Javad <ja7ad@live.com>
Date: Mon, 12 Jun 2023 16:38:45 +0330
Subject: [PATCH] update: README file

---
 README.md | 117 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 116 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index c22c271..5faa13c 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,117 @@
 # GRPC captcha validator
-GRPC captcha validation middleware
+The GRPC Captcha Validation Middleware is a Go module that provides a reusable middleware component for validating captcha challenges on GRPC servers. The middleware intercepts incoming requests, verifies the captcha challenge for the request using a configurable provider, and rejects the request if the challenge is not valid.
+
+The module is designed to be configurable, with options to specify the captcha provider, challenge validation endpoint, and custom headers for the validation request. It uses the Google Protobuf library to parse the GRPC method descriptor and extract custom options defined using protobuf extensions.
+
+## Feature
+- support Google, Cloudflare, hcaptcha provider to verify challenge
+- support unary and stream server middleware
+- captcha validation for specific rpc methods
+
+# Example
+
+example captcha for GRPC server:
+
+```protobuf
+syntax = "proto3";
+package example;
+option go_package = "github.com/GoFarsi/grpc-captcha-validation/_example/proto";
+
+import "captcha.proto";
+
+service GreetingService {
+  rpc Greeting(GreetingRequest) returns(GreetingResponse) {
+    option(captcha.captcha) = {
+      check_challenge: true,
+      provider: GOOGLE,
+    };
+  }
+
+  rpc GreetingStream(stream GreetingRequest) returns(stream GreetingResponse) {
+    option(captcha.captcha) = {
+      check_challenge: true,
+      provider: GOOGLE,
+    };
+  }
+}
+
+message GreetingRequest {
+  string name = 1;
+}
+
+message GreetingResponse {
+  string message = 1;
+}
+```
+
+```go
+package main
+
+import (
+	"context"
+	"fmt"
+	gcv "github.com/GoFarsi/grpc-captcha-validation"
+	"github.com/GoFarsi/grpc-captcha-validation/_example/proto"
+	"google.golang.org/grpc"
+	"google.golang.org/grpc/reflection"
+	"io"
+	"log"
+	"net"
+)
+
+type GreetingService struct {
+	proto.UnimplementedGreetingServiceServer
+}
+
+func (g *GreetingService) Greeting(ctx context.Context, in *proto.GreetingRequest) (*proto.GreetingResponse, error) {
+	return &proto.GreetingResponse{
+		Message: fmt.Sprintf("greeting %s", in.Name),
+	}, nil
+}
+
+func (g *GreetingService) GreetingStream(srv proto.GreetingService_GreetingStreamServer) error {
+	ctx := srv.Context()
+	for {
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+		default:
+		}
+
+		req, err := srv.Recv()
+		if err == io.EOF {
+			log.Println("exit")
+			return nil
+		}
+		if err != nil {
+			log.Printf("receive error %v", err)
+			continue
+		}
+
+		resp := proto.GreetingResponse{Message: fmt.Sprintf("Greeting %s", req.Name)}
+		if err := srv.Send(&resp); err != nil {
+			log.Printf("send error %v", err)
+		}
+	}
+}
+
+func main() {
+	listener, err := net.Listen("tcp", ":8080")
+	if err != nil {
+		log.Fatalln(err)
+	}
+
+	c := gcv.NewCaptcha("foo", "", "", "")
+
+	srv := grpc.NewServer(
+		grpc.ChainUnaryInterceptor(c.UnaryServerInterceptor()),
+		grpc.ChainStreamInterceptor(c.StreamServerInterceptor()),
+	)
+
+	reflection.Register(srv)
+
+	proto.RegisterGreetingServiceServer(srv, &GreetingService{})
+
+	log.Fatalln(srv.Serve(listener))
+}
+```