The toolkit of Go kit.

Overview

kok

The toolkit of Go kit.

Zen

  • Just write code for your business logic, generate everything else.
  • Implement the service once, consume it in various ways (in-process function call or RPC).

Features

  1. Code Generation Tool

    • Endpoint
    • Transport
      • HTTP
        • HTTP Server
        • HTTP Test
        • HTTP Client
        • OAS-v2 Documentation
      • gRPC
  2. Useful Packages

    • appx: Application framework for HTTP and CRON applications (a wrapper of appx).
    • prometheus: Prometheus metrics utilities.
    • trace: A thin wrapper of x/net/trace for Go kit.
    • werror: Classified business errors.

Installation

$ go get -u github.com/RussellLuo/kok/cmd/kokgen
Usage
$ kokgen -h
kokgen [flags] source-file interface-name
  -fmt
    	whether to make code formatted (default true)
  -out string
    	output directory (default ".")
  -pkg string
    	package name (default will infer)
  -test string
    	the YAML file that provides test-cases for HTTP (default "./http.test.yaml")
  -trace
    	whether to enable tracing

Quick Start

NOTE: The following code is located in helloworld.

  1. Define the interface

    type Service interface {
        SayHello(ctx context.Context, name string) (message string, err error)
    }
  2. Implement the service

    type Greeter struct{}
    
    func (g *Greeter) SayHello(ctx context.Context, name string) (string, error) {
        return "Hello " + name, nil
    }
  3. Add HTTP annotations

    type Service interface {
        // @kok(op): POST /messages
        SayHello(ctx context.Context, name string) (message string, err error)
    }
  4. Generate the HTTP code

    $ cd examples/helloworld
    $ kokgen ./service.go Service
  5. Consume the service

    Run the HTTP server:

    $ go run cmd/main.go
    2020/09/15 18:06:22 transport=HTTP addr=:8080

    Consume by HTTPie:

    $ http POST :8080/messages name=Tracey
    HTTP/1.1 200 OK
    Content-Length: 27
    Content-Type: application/json; charset=utf-8
    Date: Tue, 15 Sep 2020 10:06:34 GMT
    
    {
        "message": "Hello Tracey"
    }
  6. See the OAS documentation

    (Click to show details)
    $ http GET :8080/api
    HTTP/1.1 200 OK
    Content-Length: 848
    Content-Type: text/plain; charset=utf-8
    Date: Tue, 15 Sep 2020 10:08:24 GMT
    
    swagger: "2.0"
    info:
      version: "1.0.0"
      title: "Swagger Example"
      description: ""
      license:
        name: "MIT"
    host: "example.com"
    basePath: "/api"
    schemes:
      - "https"
    consumes:
      - "application/json"
    produces:
      - "application/json"
    
    paths:
      /messages:
        post:
          description: ""
          operationId: "SayHello"
          parameters:
            - name: body
              in: body
              schema:
                $ref: "#/definitions/SayHelloRequestBody"
    
          produces:
            - application/json; charset=utf-8
          responses:
            200:
              description: ""
              schema:
                $ref: "#/definitions/SayHelloResponse"
    
    
    definitions:
      SayHelloRequestBody:
        type: object
        properties:
          name:
            type: string
      SayHelloResponse:
        type: object
        properties:
          message:
            type: string

See more examples here.

HTTP

Annotations

Define the HTTP request operation
  • Key: @kok(op)

  • Value: <method> <pattern>

    • method: The request method
    • pattern: The request URL
      • NOTE: All variables (snake-case or camel-case) in pattern will automatically be bound to their corresponding method arguments (matches by name), as path parameters, if the variables are not specified as path parameters explicitly by @kok(param).
  • Example:

    type Service interface {
        // @kok(op): DELETE /users/{id}
        DeleteUser(ctx context.Context, id int) (err error)
    }
    
    // HTTP request:
    // $ http DELETE /users/101
Define the HTTP request parameters
  • Key: @kok(param)
  • Value: <argName> < in:<in>,name:<name>,required:<required>
    • argName: The name of the method argument.
      • Argument aggregation: By specifying the same argName, multiple request parameters (each one is of basic type or repeated basic type) can be aggregated into one method argument (of any type).
        • You do not need to repeat the argName, only the first one is required.
    • in:
      • path: The method argument is sourced from a path parameter.
        • Optional: All variables (snake-case or camel-case) in pattern will automatically be bound to their corresponding method arguments (matches by name), as path parameters.
      • query: The method argument is sourced from a query parameter.
        • To receive values from a multi-valued query parameter, the method argument can be defined as a slice of basic type.
      • header: The method argument is sourced from a header parameter.
      • cookie: The method argument is sourced from a cookie parameter.
        • Not supported yet.
      • request: The method argument is sourced from a property of Go's http.Request.
        • This is a special case, and only one property RemoteAddr is available now.
        • Note that parameters located in request have no relationship with OAS.
    • name: The name of the corresponding request parameter.
      • Optional: Defaults to argName if not specified.
    • required: Determines whether this parameter is mandatory.
      • Optional: Defaults to false, if not specified.
      • If the parameter location is path, this property will be set to true internally, whether it's specified or not.
  • Example:
    • Bind request parameters to simple arguments:

      type Service interface {
          // @kok(op): PUT /users/{id}
          // @kok(param): name < in:header,name:X-User-Name
          UpdateUser(ctx context.Context, id int, name string) (err error)
      }
      
      // HTTP request:
      // $ http PUT /users/101 X-User-Name:tracey
    • Bind multiple request parameters to a struct according to tags:

      type User struct {
          ID   int    `kok:"path.id"`
          Name string `kok:"query.name"`
          Age  int    `kok:"header.X-User-Age"`
      }
      
      type Service interface {
          // @kok(op): PUT /users/{id}
          // @kok(param): user
          UpdateUser(ctx context.Context, user User) (err error)
      }
      
      // HTTP request:
      // $ http PUT /users/101?name=tracey X-User-Age:1
    • Bind multiple query parameters to a struct with no tags:

      type User struct {
          Name    string
          Age     int
          Hobbies []string
      }
      
      type Service interface {
          // @kok(op): POST /users
          // @kok(param): user
          CreateUser(ctx context.Context, user User) (err error)
      }
      
      // HTTP request:
      // $ http POST /users?Name=tracey&Age=1&Hobbies=music&Hobbies=sport
    • Argument aggregation:

      type Service interface {
          // @kok(op): POST /logs
          // @kok(param): ip < in:header,name:X-Forwarded-For
          // @kok(param): ip < in:request,name:RemoteAddr
          Log(ctx context.Context, ip net.IP) (err error)
      }
      
      // The equivalent annotations.
      type Service interface {
          // @kok(op): POST /logs
          // @kok(param): ip < in:header,name:X-Forwarded-For
          // @kok(param):    < in:request,name:RemoteAddr
          Log(ctx context.Context, ip net.IP) (err error)
      }
      
      // You must customize the decoding of `ip` later (conventionally in another file named `codec.go`).
      // See examples in the `Encoding and decoding` section.
      
      // HTTP request:
      // $ http POST /logs
Define the HTTP request body
  • Key: @kok(body)
  • Value: <field>
    • field: The name of the method argument whose value is mapped to the HTTP request body.
      • Optional: When omitted, a struct containing all the arguments, which are not located in path/query/header, will automatically be mapped to the HTTP request body.
      • The special name - can be used, to define that there is no HTTP request body. As a result, every argument, which is not located in path/query/header, will automatically be mapped to one or more query parameters.
  • Example:
    • Omitted:

      type Service interface {
          // @kok(op): POST /users
          CreateUser(ctx context.Context, name string, age int) (err error)
      }
      
      // HTTP request:
      // $ http POST /users name=tracey age=1
    • Specified as a normal argument:

      type User struct {
          Name string `json:"name"`
          Age  int    `json:"age"`
      }
      
      type Service interface {
          // @kok(op): POST /users
          // @kok(body): user
          CreateUser(ctx context.Context, user User) (err error)
      }
      
      // HTTP request:
      // $ http POST /users name=tracey age=1
    • Specified as -:

      type User struct {
          Name    string   `kok:"name"`
          Age     int      `kok:"age"`
          Hobbies []string `kok:"hobby"`
      }
      
      type Service interface {
          // @kok(op): POST /users
          // @kok(body): -
          CreateUser(ctx context.Context, user User) (err error)
      }
      
      // HTTP request:
      // $ http POST /users?name=tracey&age=1&hobby=music&hobby=sport
Define the success HTTP response
  • Key: @kok(success)

  • Value: statusCode:<statusCode>,body:<body>

    • statusCode: The status code of the success HTTP response.
      • Optional: Defaults to 200 if not specified.
    • body: The name of the response field whose value is mapped to the HTTP response body.
      • Optional: When omitted, a struct containing all the results (except error) will automatically be mapped to the HTTP response body.
  • Example:

    type User struct {
        Name string `json:"name"`
        Age  int    `json:"age"`
    }
    
    type Service interface {
        // @kok(op): POST /users
        // @kok(success): statusCode:201,body:user
        CreateUser(ctx context.Context) (user User, err error)
    }

Encoding and decoding

See the HTTP Codec interface.

Take the IP decoding mentioned above as an example, we can get the real IP by customizing the built-in httpcodec.JSON:

// codec.go

import (
    "net"

    "github.com/RussellLuo/kok/pkg/codec/httpcodec"
)

type Codec struct {
    httpcodec.JSON
}

func (c Codec) DecodeRequestParams(name string, values map[string][]string, out interface{}) error {
    switch name {
    case "ip":
        // We are decoding the "ip" argument.

        remote := values["request.RemoteAddr"][0]
        if fwdFor := values["header.X-Forwarded-For"][0]; fwdFor != "" {
            remote = strings.TrimSpace(strings.Split(fwdFor, ",")[0])
        }

        ipStr, _, err := net.SplitHostPort(remote)
        if err != nil {
            ipStr = remote // OK; probably didn't have a port
        }

        ip := net.ParseIP(ipStr)
        if ip == nil {
            return fmt.Errorf("invalid client IP address: %s", ipStr)
        }

        outIP := out.(*net.IP)
        *outIP = ip
        return nil

    default:
        // Use the JSON codec for other arguments.
        return c.JSON.DecodeRequestParams(name, values, out)
    }
}

For how to use the customized Codec implementation in your HTTP server, see the profilesvc example.

OAS Schema

See the OAS Schema interface.

Documentation

Checkout the Godoc.

License

MIT

Comments
  • Rename this project

    Rename this project

    Motivation

    In some cultures, the pronunciation of kok may lead to misunderstanding. (See comments here and here.)

    New name

    The new name under consideration is kin, which means "Kin Is Not just a kit of Go kit".

    Other related names:

    • Module path
      • github.com/RussellLuo/kin
    • Code generation tool
      • kingen
    • Annotation directives
      • //kin:op
      • //kin:param
      • //kin:body
      • //kin:success
      • //kin:oas
      • //kin:alias
      • //kin:grpc
    • Struct tags
      • kin:"..."

    Tasks

    • Rename the repo
    • Update the code
    • Update the docs
    opened by RussellLuo 4
  • Invalid literal error when generating code for an Interface

    Invalid literal error when generating code for an Interface

    Hi @RussellLuo thanks creating kun, great toolkit! i'm running into a (minor) issue with the generated returnErr when generating an http client.

    As an example, suppose I have this service with a method that contains an interface (i.e. Animal)

    package service 
    
    //go:generate kungen -force ./service.go Service
    type Service interface {
    	//kun:op GET /animal/{id}
    	Find(id string) (Animal, error)
    }
    
    type Animal interface {
    	IsAnimal()
    }
    

    After generating the code http_client.go will contain the following:

    req, err := http.NewRequest("GET", u.String(), nil)
    if err != nil {
    	return Animal{}, err
    }
    

    returning Animal{} results in an InvalidLiteral error.

    If you're open to contributions I created a PR: https://github.com/RussellLuo/kun/pull/29 Feel free to give feedback, or let me know if you'd like to see tests for contributions:)

    opened by nicolaa5 0
  • annotation: Add support for multiple HTTP operations

    annotation: Add support for multiple HTTP operations

    Sometimes, a Go method needs to correspond to more than one URI (or HTTP method). For example:

    type Service interface {
    	//kun:op GET /messages/{messageID}
    	//kun:op GET /users/{userID}/messages/{messageID}
    	GetMessage(ctx context.Context, userID string, messageID string) (text string, err error)
    }
    

    This will enable the following two alternative HTTP to Go Method mappings:

    HTTP | Go Method -- | -- GET /messages/123456 | GetMessage(ctx, "", "123456") GET /users/me/messages/123456 | GetMessage(ctx, "me", "123456")

    This feature is much like (and is partially inspired by) gRPC's additional_bindings option (also see Multiple URI bindings).

    This closes #25.

    opened by RussellLuo 0
  • annotation: Add support for multiple HTTP operations

    annotation: Add support for multiple HTTP operations

    Sometimes, a Go method needs to correspond to more than one URI (or HTTP method). For example:

    type Service interface {
    	//kun:op GET /messages/{messageID}
    	//kun:op GET /users/{userID}/messages/{messageID}
    	GetMessage(ctx context.Context, userID string, messageID string) (text string, err error)
    }
    

    This will enable the following two alternative HTTP to Go-method mappings:

    HTTP | Go Method -- | -- GET /messages/123456 | GetMessage(ctx, "", "123456") GET /users/me/messages/123456 | GetMessage(ctx, "me", "123456")

    This feature is much like (and is partially inspired by) gRPC's additional_bindings option (also see Multiple URI bindings).

    enhancement 
    opened by RussellLuo 0
  • Minor syntax improvements for `//kok:param`

    Minor syntax improvements for `//kok:param`

    Syntax improvements

    Original syntax (after #18):

    • //kok:param <argName> [<parameter> [; <parameter2> [; ...]]]
      • parameter: in=<in> name=<name> required=<required> type=<type> descr=<descr>

    New syntax:

    • //kok:param <argName> [<parameter> [, <parameter2> [, ...]]]
      • parameter: in=<in> name=<name> required=<required> type=<type> descr=<descr>
    • NOTE: If multiple method arguments are involved, you may need to apply multiple bindings. This can be done by adding a new //kok:param directive, or by appending the binding to the end of the last //kok:param directive in a semicolon-separated list.

    Example

    After the above syntax improvements, here are the equivalent annotations:

    One binding per //kok:param

    type Service interface {
        //kok:op POST /users
        //kok:param name
        //kok:param age in=query
        //kok:param ip in=header name=X-Forwarded-For, in=request name=RemoteAddr
        CreateUser(ctx context.Context, name string, age int, ip net.IP) (err error)
    }
    
    // HTTP request:
    // $ http POST /users?name=tracey&age=1
    

    Multiple bindings in a single //kok:param

    type Service interface {
        //kok:op POST /users
        //kok:param name; age in=query; ip in=header name=X-Forwarded-For, in=request name=RemoteAddr
        CreateUser(ctx context.Context, name string, age int, ip net.IP) (err error)
    }
    
    // HTTP request:
    // $ http POST /users?name=tracey&age=1
    

    Multiple bindings in a single //kok:param (but using backslash for better readability)

    type Service interface {
        //kok:op POST /users
        //kok:param name; \
        //          age in=query; \
        //          ip in=header name=X-Forwarded-For, in=request name=RemoteAddr
        CreateUser(ctx context.Context, name string, age int, ip net.IP) (err error)
    }
    
    // HTTP request:
    // $ http POST /users?name=tracey&age=1
    
    opened by RussellLuo 0
  • Redesign the annotation syntax

    Redesign the annotation syntax

    Motivation

    1. Follow the Go conventions for comment directives (and this).
    2. Provide a unified annotation syntax for both comments and struct tags.
    3. Make it possible to apply Argument aggregation in a single-line annotation.
    4. Improve the comment syntax for manipulating HTTP request/response body fields.

    Proposed annotation syntax

    HTTP

    1. Define the HTTP operation

      • Directive: //kok:op

      • Arguments: <method> <pattern>

        • ...
      • Examples:

        type Service interface {
            //kok:op DELETE /users/{id}
            DeleteUser(ctx context.Context, id int) (err error)
        }
        
        // HTTP request:
        // $ http DELETE /users/101
        
    2. Define the HTTP request parameters

      • Directive: //kok:param
      • Arguments: <argName> [<parameter> [; <parameter2> [; ...]]]
        • parameter: in=<in> name=<name> required=<required> type=<type> descr=<descr>
          • ...
      • Examples:
        • Bind request parameters to simple arguments:

          type Service interface {
              //kok:op PUT /users/{id}
              //kok:param name in=header name=X-User-Name
              UpdateUser(ctx context.Context, id int, name string) (err error)
          }
          
          // HTTP request:
          // $ http PUT /users/101 X-User-Name:tracey
          
        • Bind multiple request parameters to a struct according to tags:

          type User struct {
              ID   int    `kok:"in=path"`  // name defaults to snake case `id`
              Name string `kok:"in=query"` // name defaults to snake case `name`
              Age  int    `kok:"in=header name=X-User-Age"`
          }
          
          type Service interface {
              //kok:op PUT /users/{id}
              //kok:param user
              UpdateUser(ctx context.Context, user User) (err error)
          }
          
          // HTTP request:
          // $ http PUT /users/101?name=tracey X-User-Age:1
          
        • Bind multiple query parameters to a struct with no tags:

          type User struct {
              Name    string   // equivalent to `kok:"in=query name=name"`
              Age     int      // equivalent to `kok:"in=query name=age"`
              Hobbies []string // equivalent to `kok:"in=query name=hobbies"`
          }
          
          type Service interface {
              //kok:op POST /users
              //kok:param user
              CreateUser(ctx context.Context, user User) (err error)
          }
          
          // HTTP request:
          // $ http POST /users?name=tracey&age=1&hobbies=music&hobbies=sport
          
        • Argument aggregation:

          type Service interface {
              //kok:op POST /logs
              //kok:param ip in=header name=X-Forwarded-For; in=request name=RemoteAddr
              Log(ctx context.Context, ip net.IP) (err error)
          }
          
          // The equivalent annotations =>
          // (using backslash `\` for line continuation)
          
          type Service interface {
              //kok:op POST /logs
              //kok:param ip in=header name=X-Forwarded-For; \
              //             in=request name=RemoteAddr
              Log(ctx context.Context, ip net.IP) (err error)
          }
          
          // HTTP request:
          // $ http POST /logs
          
    3. Define the HTTP request body

      • Directive: //kok:body
      • Arguments: <field> or <manipulation> [; <manipulation2> [; ...]]
        • manipulation: <argName> name=<name> type=<type> descr=<descr>
          • ...
      • Examples:
        • Omitted:

          type Service interface {
              //kok:op POST /users
              CreateUser(ctx context.Context, name string, age int) (err error)
          }
          
          // HTTP request:
          // $ http POST /users name=tracey age=1
          
        • Specified as a normal argument:

          type User struct {
              Name string `json:"name"`
              Age  int    `json:"age"`
          }
          
          type Service interface {
              //kok:op POST /users
              //kok:body user
              CreateUser(ctx context.Context, user User) (err error)
          }
          
          // HTTP request:
          // $ http POST /users name=tracey age=1
          
        • Specified as -:

          type User struct {
              Name    string
              Age     int
              Hobbies []string `kok:"name=hobby"`
          }
          
          type Service interface {
              //kok:op POST /users
              //kok:body -
              CreateUser(ctx context.Context, user User) (err error)
          }
          
          // HTTP request:
          // $ http POST /users?name=tracey&age=1&hobby=music&hobby=sport
          
    4. Define the success HTTP response

      • Directive: //kok:success

      • Arguments: statusCode=<statusCode> body=<body> manip=`<manipulation> [; <manipulation2> [; ...]]`

        • manipulation: <argName> name=<name> type=<type> descr=<descr>
          • ...
      • Examples:

        type User struct {
            Name string `json:"name"`
            Age  int    `json:"age"`
        }
        
        type Service interface {
            //kok:op POST /users
            //kok:success statusCode=201 body=user
            CreateUser(ctx context.Context) (user User, err error)
        }
        
    5. Define the OAS metadata

      • Directive: //kok:oas

      • Arguments: <property>=<value>

      • Examples:

        // This is the API documentation of User.
        //kok:oas docsPath=/api-docs
        //kok:oas title=User API
        //kok:oas version=1.0.0
        //kok:oas basePath=/v1
        //kok:oas tags=user
        type Service interface {
            //kok:op POST /users
            CreateUser(ctx context.Context, name string, age int) (err error)
        }
        
    6. Define the annotation alias

      • Directive: //kok:alias

      • Arguments: <name>=`<value>`

      • Examples:

        type Service interface {
            //kok:op POST /users
            //kok:param operatorID in=header name=Authorization required=true
            CreateUser(ctx context.Context, operatorID int) (err error)
        
            //kok:op DELETE /users/{id}
            //kok:param operatorID in=header name=Authorization required=true
            DeleteUser(ctx context.Context, id, operatorID int) (err error)
        }
        
        // The equivalent annotations =>
        
        //kok:alias opID=`operatorID in=header name=Authorization required=true`
        type Service interface {
            //kok:op POST /users
            //kok:param $opID
            CreateUser(ctx context.Context, operatorID int) (err error)
        
            //kok:op DELETE /users/{id}
            //kok:param $opID
            DeleteUser(ctx context.Context, id, operatorID int) (err error)
        }
        

    gRPC

    • Directive: //kok:grpc
    • Arguments: request=<request> response=<response>
    • Examples:
      • Omitted:

        type Service interface {
            //kok:grpc
            CreateUser(ctx context.Context, name string, age int) (err error)
        }
        
        // gRPC request:
        // $ grpcurl -d '{"name": "tracey", "age": 1}' ... pb.Service/CreateUser
        
      • Specified:

        type User struct {
            Name string `json:"name"`
            Age  int    `json:"age"`
        }
        
        type Service interface {
            //kok:grpc request=user
            CreateUser(ctx context.Context, user User) (err error)
        }
        
        // gRPC request:
        // $ grpcurl -d '{"name": "tracey", "age": 1}' ... pb.Service/CreateUser
        
    opened by RussellLuo 0
  • Improve the interface parser

    Improve the interface parser

    Since the underlying interface parser is borrowed from the old version of moq, kokgen has the same legacy issues as moq:

    • https://github.com/matryer/moq/issues/68
    • https://github.com/matryer/moq/issues/94

    In order to address these issues, we must improve the interface parser by leveraging the new version of moq (thanks to https://github.com/matryer/moq/pull/141).

    Since the core packages for interface parsing in moq are internal, we have to copy the code from moq instead.

    opened by RussellLuo 0
  • Add support for using blank identifiers in `@kok(param)`

    Add support for using blank identifiers in `@kok(param)`

    Problem

    Sometimes, an HTTP request parameter is only used in the Transport/Endpoint layer, and no further argument binding (in the Service layer) is needed.

    Taking the following GetUser operation as an example:

    type Service interface {
    	// @kok(op): GET /users/{id}
    	// @kok(success): body:user
    	GetUser(ctx context.Context, id int) (user User, err error)
    }
    

    In order to protect the operation, we may implement service-to-service authentication via the Authorization header. Meanwhile, there is no corresponding argument in GetUser to be mapped to.

    So how to represent this Authorization header in kok's HTTP annotation?

    Proposed Solution

    Add support for the blank identifier __ (double underscore, similar to Go's blank identifier) in @kok(param):

    type Service interface {
    	// @kok(op): GET /users/{id}
    	// @kok(param): __ < in:header,name:Authorization,required:true
    	// @kok(success): body:user
    	GetUser(ctx context.Context, id int) (user User, err error)
    }
    

    And here is the possible codec.go for the Authorization header:

    import (
    	"fmt"
    
    	"github.com/RussellLuo/kok/pkg/codec/httpcodec"
    )
    
    const (
    	authPrivateKey = "AUTH_PRIVATE_KEY"
    )
    
    // AuthCodec is used to encode and decode the `Authorization` header. It can be reused wherever needed.
    type AuthCodec struct{}
    
    func (c AuthCodec) Decode(in []string, out interface{}) error {
    	// NOTE: never use out, which is nil here.
    
    	if len(in) == 0 || in[0] != authPrivateKey {
    		return fmt.Errorf("authentication failed")
    	}
    	return nil
    }
    
    func (c AuthCodec) Encode(in interface{}) (out []string) {
    	// NOTE: never use in, which is nil here.
    
    	return []string{authPrivateKey}
    }
    
    func NewCodecs() *httpcodec.DefaultCodecs {
    	// Use AuthCodec to encode and decode the argument named "__", if exists,
    	// for the operation named "GetUser".
    	return httpcodec.NewDefaultCodecs(nil,
    		httpcodec.Op("GetUser", httpcodec.NewPatcher(httpcodec.JSON{}).Param("__", AuthCodec{})))
    }
    

    Multiple blank identifiers

    In complicated cases, where multiple blank identifiers are involved and need to be differentiated from one another (typically for applying different encoders and decoders), we can use meaningful names, each with a double underscore prefix __ (e.g. __auth).

    In summary, any name with a double underscore prefix __ is a valid blank identifier:

    • __
    • __auth
    • __other
    opened by RussellLuo 0
  • Add support for the gRPC transport

    Add support for the gRPC transport

    • [x] Generate the .proto file from the service definition in Go
    • [x] Compile the .proto file to the gRPC definition
    • [x] Adapt the gRPC definition to Go kit
    opened by RussellLuo 0
  • Add support for `@kok(alias)`

    Add support for `@kok(alias)`

    Lengthy

    type User interface {
        // @kok(op): POST /users
        // @kok(param): operatorID < in:header,name:Authorization,required:true
        Create(ctx context.Context, operatorID int) (err error)
    
        // @kok(op): GET /users/{id}
        // @kok(param): operatorID < in:header,name:Authorization,required:true
        Read(ctx context.Context, id, operatorID int) (err error)
    
        // @kok(op): PUT /users/{id}
        // @kok(param): operatorID < in:header,name:Authorization,required:true
        Update(ctx context.Context, id, operatorID int) (err error)
    
        // @kok(op): DELETE /users/{id}
        // @kok(param): operatorID < in:header,name:Authorization,required:true
        Delete(ctx context.Context, id, operatorID int) (err error)
    }
    

    Simplified

    // @kok(alias): auth=`in:header,name:Authorization,required:true`
    type User interface {
        // @kok(op): POST /users
        // @kok(param): operatorID < $auth
        Create(ctx context.Context, operatorID int) (err error)
    
        // @kok(op): GET /users/{id}
        // @kok(param): operatorID < $auth
        Read(ctx context.Context, id, operatorID int) (err error)
    
        // @kok(op): PUT /users/{id}
        // @kok(param): operatorID < $auth
        Update(ctx context.Context, id, operatorID int) (err error)
    
        // @kok(op): DELETE /users/{id}
        // @kok(param): operatorID < $auth
        Delete(ctx context.Context, id, operatorID int) (err error)
    }
    

    Or

    // @kok(alias): opID=`operatorID < in:header,name:Authorization,required:true`
    type User interface {
        // @kok(op): POST /users
        // @kok(param): $opID
        Create(ctx context.Context, operatorID int) (err error)
    
        // @kok(op): GET /users/{id}
        // @kok(param): $opID
        Read(ctx context.Context, id, operatorID int) (err error)
    
        // @kok(op): PUT /users/{id}
        // @kok(param): $opID
        Update(ctx context.Context, id, operatorID int) (err error)
    
        // @kok(op): DELETE /users/{id}
        // @kok(param): $opID
        Delete(ctx context.Context, id, operatorID int) (err error)
    }
    
    opened by RussellLuo 0
  • Add support for request validation

    Add support for request validation

    Take helloworld as an example, this is the original construction code:

    https://github.com/RussellLuo/kok/blob/1a22aefc486c8250d788a4d36012af5b391425ed/examples/helloworld/cmd/main.go#L22

    If we want to add request validation for the SayHello operation, we can change the above code as follows:

    1. Validation rules written in Go

    validators := []httpoption.NamedValidator{
        httpoption.Op("SayHello", httpoption.FuncValidator(func(value interface{}) error {
            req := value.(*helloworld.SayHelloRequest)
            if len(req.Name) > 10 {
                return werror.Wrapf(gcode.ErrInvalidArgument, "name: length exceeds 10")
            }
    
            reVarName := regexp.MustCompile(`^\w+$`)
            if !reVarName.MatchString(req.Name) {
                return werror.Wrapf(gcode.ErrInvalidArgument, "name: invalid name format")
            }
    
            return nil
        })),
    }
    r := helloworld.NewHTTPRouter(svc, httpcodec.NewDefaultCodecs(nil), httpoption.RequestValidators(validators...))
    

    2. Validation rules written in DSL of validating

    validators := []httpoption.NamedValidator{
        httpoption.Op("SayHello", helloworld.ValidateSayHelloRequest(func(req *helloworld.SayHelloRequest) v.Schema {
            return v.Schema{
                v.F("name", &req.Name): v.All(
                    v.Len(0, 10).Msg("length exceeds 10"),
                    v.Match(regexp.MustCompile(`^\w+$`)).Msg("invalid name format"),
                ),
            }
        })),
    }
    r := helloworld.NewHTTPRouter(svc, httpcodec.NewDefaultCodecs(nil), httpoption.RequestValidators(validators...))
    

    NOTE:

    • The ValidateSayHelloRequest() function is designed to be generated by kokgen
    • The validation of each validator will be triggered in its corresponding DecodeRequestFunc (https://github.com/go-kit/kit/issues/908#issuecomment-526874228)
    opened by RussellLuo 0
  • Async communication

    Async communication

    i really like the approach this framework takes of using annotations.

    i would like to try to add async communication generators .

    i use NATS quite a bit . It’s a message bus and broker .

    https://github.com/nats-io/nats.go

    It has HTTP / web socket and tcp transports built in.

    So for iot people use the tcp layer . But for web they use the http and web sockets .

    Nats is globally clustered , self load balancing and has build in security. It also has a clustered kv that replaced etc and consul. So it remove the need for a lot of other layers typically needed for global internet scale systems engineering .

    It’s 100% golang and runs on anything .

    It can do RPC and PUB SUB also.

    You can use protobufs, json , anything you want serialisation . It does not care .

    I don’t know how familiar you are with NATS . But just let me know if this is something if interest.

    i currently use it in iot, web, desktop and servers .

    —-

    there is a standard approach to async communications that is emerging also called “async api”.

    https://www.asyncapi.com/

    It’s like openapi but for async.

    it also has generators but like openapi takes the approach of you first writing your api description in json or yaml and then code generating from that .

    it’s quite possible however to generate an async api document using kok !!!! This I think would be pretty cool because then others can generate the client in whatever language they want .

    https://github.com/orgs/asyncapi/repositories?q=&type=&language=go&sort=

    opened by gedw99 17
Releases(v0.4.4)
  • v0.4.4(Aug 7, 2022)

    • generator: Improve the endpoint generator (09c7c20a72a0ac774c4cc9b5bf4f8db2257bab78)
    • generator: Improve the HTTP-client generator (8bd4856a2d7839af181769061202d9c2dea0908c)
    • generator: Add support for generating Event Subscribers & Publishers (37b124c49107cd00fc3543c004244fd4409f9e62, 48f79118ced5e1c822556edfc3a5b827dc112e38, d3832b6d1b6e96f270a0b7b75c93f8ed35eb441a, 32404effc3cf21f68274ca848bfe92c04132dec8)
    • generator: Remove the HTTP-test generator in favor of protogodev/httptest (36fbf97d77af7761f85a4dbdc5024e56e733c9f2)
    • pkgtool: Fix PkgPathFromDir and improve PkgNameFromDir (7e9b8d48e50f0c0af5d82f7f310378dfcad9bde2, 8bf9f62432d5af957d2f5cbc91cccfdc02fe9b03)
    • oas2: Add support for content negotiation (4dbf13c6d865d70a2c490311af855dcb7a04d958)
    • Refactor appx (a434bc454f20f5e3ce023497d364090bb47d9e30)
    • Minor improvements (207179dfaa358bcd7c11c9b412d5029f0fa1b978)
    Source code(tar.gz)
    Source code(zip)
  • v0.4.3(Mar 18, 2022)

    • generator: Improve the OAS generator (https://github.com/RussellLuo/kun/commit/f439675f295a7a2843234d1add5451ee26c4e80d)
    • generator: Improve the HTTP-server generator (https://github.com/RussellLuo/kun/commit/0342697a4a4f9e0dda26c7aad72191d7cd9c0849, https://github.com/RussellLuo/kun/commit/ab5badafab5175554dd8a7db28c8f85ecc5d817f)
    • annotation: Make //kun:body - actually work (https://github.com/RussellLuo/kun/commit/0e5b68e9d6d3c19683eb9f34f06b4c2a409ff1f5, https://github.com/RussellLuo/kun/commit/2c3e4393bca32f38991f404d767df75ecb8f1ead)
    • annotation: Make //kun:alias actually work (https://github.com/RussellLuo/kun/commit/bd2148d2d21aadd63ba16c8df5f7c42b1dbcc56b)
    • Remove deprecated packages (https://github.com/RussellLuo/kun/commit/c0874b36a36ae50d19f67a32dc0bbd6079e90e1e, https://github.com/RussellLuo/kun/commit/c5cb0894120eec0ace31ae1b6cd2d820ba13d714)
    • Rename pkg/httpoption2 to pkg/httpoption (https://github.com/RussellLuo/kun/commit/bda7f3ab5cb4fad8787d32cdfbaa93e900957599)
    • annotation: Remove support for old annotation syntax (https://github.com/RussellLuo/kun/commit/24baa6362ee871793d3861893131921ad564279d)
    • annotation: Add support for using single quotes in //kun:param (https://github.com/RussellLuo/kun/commit/7ebd937f8641d0c8032c0ffc974a3598e779a230)
    Source code(tar.gz)
    Source code(zip)
  • v0.4.2(Feb 26, 2022)

  • v0.4.1(Dec 13, 2021)

  • v0.4.0(Nov 18, 2021)

  • v0.3.2(Nov 1, 2021)

    • Improve the interface parser (#17)
    • Improve the HTTP-test generator to handle response body properly
    • Improve the OAS package to handle recursive types properly
    Source code(tar.gz)
    Source code(zip)
  • v0.3.1(Jul 14, 2021)

    • Remove deprecated pkg/codec/httpv2
    • Remove deprecated LegacyResponseSchema
    • Add support for using blank identifiers in @kok(param) (#15)
    • Add support for @kok(alias) (#11)
    • Improve documentation
    Source code(tar.gz)
    Source code(zip)
  • v0.3.0(Jul 5, 2021)

    • Add an option "-snake" for kokgen
    • Fix the path parameter binding
    • Improve generators
    • Add an option "-flat" for kokgen
    • Add support for generating gRPC server (#14, https://github.com/RussellLuo/kok/commit/3c0e3ad5fe4f2148b8f2b99ca107da9ad6a0e601, https://github.com/RussellLuo/kok/commit/c15265c1427ea68a16314b12b57fa98138a785fe, https://github.com/RussellLuo/kok/commit/c35bd68be14f99e34d4bb96b9d237f446ac9d583)
    • Add gRPC examples (helloworldgrpc and profilesvcgrpc)
    Source code(tar.gz)
    Source code(zip)
  • v0.2.10(Jun 10, 2021)

    • Remove deprecated functions DecodeSliceToBasic()/EncodeBasicToSlice() and DecodeMapToStruct()/EncodeStructToMap()
    • Remove deprecated package pkg/codec/http
    • Cleanup werror.Error
    • Improve the HTTP-test generator to handle variadic arguments properly
    • Enhance @kok(body) to support optional tags "name" and "descr"
    • Add support for request validation (#10)
    • Upgrade appx and improve httpapp and cronapp
    Source code(tar.gz)
    Source code(zip)
  • v0.2.9(May 20, 2021)

  • v0.2.8(May 11, 2021)

    • Add support for patching existing codecs (#8)
    • Add BasicParam and StructParams
    • Let users handle the cases where required fields are missing
    Source code(tar.gz)
    Source code(zip)
  • v0.2.7(May 7, 2021)

  • v0.2.6(Apr 28, 2021)

    • Enhance the OAS generator to extract descriptions from interface docs
    • Add support for specifying OAS metadata by using @kok(oas)
    • Remove support for @kok(tag)
    • Add an option descr for @kok(param)
    • Add support for specifying OAS descriptions in the Kok tag (e.g. kok:",descr:DESCRIPTION")
    Source code(tar.gz)
    Source code(zip)
  • v0.2.5(Apr 21, 2021)

    • Improve the OAS package to handle the following types properly:
      • time.Time
      • arrays of nil map[string]interface{}
    • Move gen/util/misc to pkg/caseconv
    • Improve the OAS generator to handle multi-valued parameters properly
    • Ensure that path parameters are always required
    • Add support for changing the OAS type of a struct field by using the Kok tag (e.g. kok:",type:string")
    • Add support for @kok(tag), which is mainly used for specifying OAS tags
    Source code(tar.gz)
    Source code(zip)
  • v0.2.4(Apr 15, 2021)

    • Improve addSubDefinition to handle pointers to basic types properly
    • Add support for types float32 and float64
    • Improve the OAS package to handle arrays and slices more properly
    Source code(tar.gz)
    Source code(zip)
  • v0.2.3(Apr 7, 2021)

  • v0.2.2(Mar 12, 2021)

  • v0.2.1(Mar 8, 2021)

  • v0.2.0(Mar 8, 2021)

  • v0.1.0(Mar 3, 2021)

Owner
Luo Peng
Luo Peng
Tpf2-tpnetmap-toolkit - A toolkit to create svg map images from TransportFever2 world data

tpf2-tpnetmap-toolkit TransportFever2 のワールドデータから svg のマップ画像を作成するツールキットです。 1. 導入方

Nosrith 1 Feb 17, 2022
An idiomatic Go REST API starter kit (boilerplate) following the SOLID principles and Clean Architecture

Go RESTful API Starter Kit (Boilerplate) This starter kit is designed to get you up and running with a project structure optimized for developing REST

Qiang Xue 1.1k Dec 2, 2022
This is an example to demonstrate implementation golang microservices using domain driven design principles and sugestions from go-kit

go-kit DDD Domain Driven Design is prevelent and rising standard for organizing your microservice code. This design architecture emphasis on Code orga

Sourabh Mandal 1 Feb 9, 2022
This tool generates Go language bindings of services in protobuf definition files for go-kit

protoc-gen-go-kit This tool generates Go language bindings of services in protobuf definition files for go-kit. Installation $ go install github.com/x

X64FUN 1 Nov 9, 2021
Astro Starter Kit: Docs Site

Astro Starter Kit: Docs Site npm init astro -- --template docs Features ✅ Full Markdown support ✅ Responsive mobile-friendly design ✅ Sidebar navigat

Connor McCutcheon 2 Apr 10, 2022
Protoc plugin used to generate go-kit grpc code

protoc-gen-gokit-endpoint protoc plugin used to generate go-kit grpc code 安装 go install github.com/wwbweibo/protoc-gen-gokit-endpoint/cmd/protoc-gen-g

wangweibo 4 Sep 29, 2022
Protoc plugin used to generate go-kit grpc code

protoc-gen-gokit-endpoint protoc plugin used to generate go-kit grpc code 安装 go

wangweibo 4 Sep 29, 2022
⚔ Personal Golang starter kit with an engineer research perspective, expressjs developer friendly, and aims for rapid app development.

Goku (WIP; Author Only) ⚔ Personal Golang starter kit with an engineer research perspective, expressjs developer friendly, and aims for rapid app deve

Fauzan 1 Jan 6, 2022
Huawei-push-authorizator - Huawei Push Kit authorizator in time

huawei-push-authorizator Huawei Push Kit authorizator in time Why? To send push

Evgeniy Kudinov 1 Jan 3, 2022
Netkit - A type parameter(generics) net kit, support tcp kcp, customize packet

Netkit Netkit is a type parameter(generics) golang package Get Started Need Go i

null 1 Jan 12, 2022
Awpark - Development kit via Alfred Workflow

AWPark Alfred Workflow for engineer. Alfred Workflow Store Search and install Wo

null 57 Oct 26, 2022
This project implements p11-kit RPC server protocol, allowing Go programs to act as a PKCS #11 module without the need for cgo

PKCS #11 modules in Go without cgo This project implements p11-kit RPC server protocol, allowing Go programs to act as a PKCS #11 module without the n

Google 43 Oct 8, 2022
Realworld implementation written with Go using go-kit!

This project is an implementation of the RealWorld project using Go utilizing go-kit as an application framework. The project heavily utilizes Docker

Joey McKenzie 21 Nov 23, 2022
Concurrent task runner, developer's routine tasks automation toolkit. Simple modern alternative to GNU Make 🧰

taskctl - concurrent task runner, developer's routine tasks automation toolkit Simple modern alternative to GNU Make. taskctl is concurrent task runne

null 231 Dec 5, 2022
A memcached binary protocol toolkit for go.

gomemcached This is a memcached binary protocol toolkit in go. It provides client and server functionality as well as a little sample server showing h

Dustin Sallings 315 Nov 9, 2022
Building powerful interactive prompts in Go, inspired by python-prompt-toolkit.

go-prompt A library for building powerful interactive prompts inspired by python-prompt-toolkit, making it easier to build cross-platform command line

Masashi SHIBATA 4.7k Nov 29, 2022
PostgreSQL driver and toolkit for Go

pgx - PostgreSQL Driver and Toolkit pgx is a pure Go driver and toolkit for PostgreSQL. pgx aims to be low-level, fast, and performant, while also ena

Jack Christensen 6.4k Dec 5, 2022
Now is a time toolkit for golang

Now Now is a time toolkit for golang Install go get -u github.com/jinzhu/now Usage Calculating time based on current time import "github.com/jinzhu/n

Jinzhu 3.9k Dec 3, 2022
Image processing library and rendering toolkit for Go.

blend Image processing library and rendering toolkit for Go. (WIP) Installation: This library is compatible with Go1. go get github.com/phrozen/blend

Guillermo Estrada 61 Nov 11, 2022
gui toolkit for go

Simple GUI toolkit with go Install You will need to install gtk-dev files. go get github.com/zozor/hgui The idea This is a gui toolkit that relies on

Anders 58 Feb 14, 2021