binder

README

binder

Parameter Binding Verification Plugin for Struct Handler.

Usage

import "github.com/henrylee2cn/teleport/v6/plugin/binder"

Param-Tags

tag	key	required	value	desc
param	meta	no	(name e.g.param:"<meta:id>")	It indicates that the parameter is from the meta.
param	swap	no	name (e.g.param:"<swap:id>")	It indicates that the parameter is from the context swap.
param	desc	no	(e.g.param:"<desc:id>")	Parameter Description
param	len	no	(e.g.param:"<len:3:6>")	Length range [a,b] of parameter's value
param	range	no	(e.g.param:"<range:0:10>")	Numerical range [a,b] of parameter's value
param	nonzero	no	-	Not allowed to zero
param	regexp	no	(e.g.param:"<regexp:^\\w+$>")	Regular expression validation
param	stat	no	(e.g.param:"<stat:100002:wrong password format>")	Custom error code and message

NOTES:

• param:"-" means ignore
• Encountered untagged exportable anonymous structure field, automatic recursive resolution
• Parameter name is the name of the structure field converted to snake format
• If the parameter is not from meta or swap, it is the default from the body
• Support for multiple rule combinations, e.g.param:"<regexp:^\\w+$><len:6:8><stat:100002:wrong password format>"

Field-Types

base	slice	special
string	[]string	[][]byte
byte	[]byte	[][]uint8
uint8	[]uint8	struct
bool	[]bool
int	[]int
int8	[]int8
int16	[]int16
int32	[]int32
int64	[]int64
uint8	[]uint8
uint16	[]uint16
uint32	[]uint32
uint64	[]uint64
float32	[]float32
float64	[]float64

Test

package binder_test

import (
	"testing"
	"time"

	tp "github.com/henrylee2cn/teleport/v6"
	"github.com/henrylee2cn/teleport/v6/plugin/binder"
)

type (
	Arg struct {
		A int
		B int    `param:"<range:1:100>"`
		C string `param:"<regexp:^[1-9]\\d*$>"`
		Query
		XyZ       string  `param:"<meta><nonzero><stat: 100002: Parameter cannot be empty>"`
		SwapValue float32 `param:"<swap><nonzero>"`
	}
	Query struct {
		X string `param:"<meta:_x>"`
	}
)

type P struct{ tp.CallCtx }

func (p *P) Divide(arg *Arg) (int, *tp.Status) {
	tp.Infof("meta arg _x: %s, xy_z: %s, swap_value: %v", arg.Query.X, arg.XyZ, arg.SwapValue)
	return arg.A / arg.B, nil
}

type SwapPlugin struct{}

func (s *SwapPlugin) Name() string {
	return "swap_plugin"
}
func (s *SwapPlugin) PostReadCallBody(ctx tp.ReadCtx) *tp.Status {
	ctx.Swap().Store("swap_value", 123)
	return nil
}

func TestBinder(t *testing.T) {
	bplugin := binder.NewStructArgsBinder(nil)
	srv := tp.NewPeer(
		tp.PeerConfig{ListenPort: 9090},
	)
	srv.PluginContainer().AppendRight(bplugin)
	srv.RouteCall(new(P), new(SwapPlugin))
	go srv.ListenAndServe()
	time.Sleep(time.Second)

	cli := tp.NewPeer(tp.PeerConfig{})
	sess, stat := cli.Dial(":9090")
	if !stat.OK() {
		t.Fatal(stat)
	}
	var result int
	stat = sess.Call("/p/divide", &Arg{
		A: 10,
		B: 2,
		C: "3",
	},
		&result,
		tp.WithSetMeta("_x", "testmeta_x"),
		tp.WithSetMeta("xy_z", "testmeta_xy_z"),
	).Status()
	if !stat.OK() {
		t.Fatal(stat)
	}
	t.Logf("10/2=%d", result)
	stat = sess.Call("/p/divide", &Arg{
		A: 10,
		B: 5,
		C: "3",
	}, &result).Status()
	if stat.OK() {
		t.Fatal(stat)
	}
	t.Logf("10/5 error:%v", stat)
	stat = sess.Call("/p/divide", &Arg{
		A: 10,
		B: 0,
		C: "3",
	}, &result).Status()
	if stat.OK() {
		t.Fatal(stat)
	}
	t.Logf("10/0 error:%v", stat)
}

test command:

go test -v -run=TestBinder

Documentation

Overview

Package binder is Parameter Binding Verification Plugin for Struct Handler.

Copyright 2018 HenryLee. All Rights Reserved.

Licensed 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.

Index

• Constants
• type ErrorFunc
• type Param
  • func (param *Param) Description() string
  • func (param *Param) Name() string
  • func (param *Param) Raw() interface{}
• type Params
• type StructArgsBinder
  • func NewStructArgsBinder(fn ErrorFunc) *StructArgsBinder
  • func (*StructArgsBinder) Name() string
  • func (s *StructArgsBinder) PostReadCallBody(ctx tp.ReadCtx) *tp.Status
  • func (s *StructArgsBinder) PostReg(h *tp.Handler) error
  • func (s *StructArgsBinder) SetErrorFunc(fn ErrorFunc)

Constants

const (
	TAG_PARAM        = "param"   // request param tag name
	TAG_IGNORE_PARAM = "-"       // ignore request param tag value
	KEY_META         = "meta"    // meta param(optional), value means parameter(optional)
	KEY_SWAP         = "swap"    // swap param from the context swap(ctx.Swap()) (optional), value means parameter(optional)
	KEY_DESC         = "desc"    // request param description
	KEY_LEN          = "len"     // length range of param's value
	KEY_RANGE        = "range"   // numerical range of param's value
	KEY_NONZERO      = "nonzero" // param`s value can not be zero
	KEY_REGEXP       = "regexp"  // verify the value of the param with a regular expression(param value can not be null)
	KEY_RERR         = "stat"    // the custom error code and message for binding or validating
)

struct binder parameters'tag

Types

type ErrorFunc

type ErrorFunc func(handlerName, paramName, reason string) *tp.Status

ErrorFunc creates an relational error.

type Param

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

Param use the struct field to define a request parameter model

func (*Param) Description

func (param *Param) Description() string

Description gets the description value for the param

func (*Param) Name

func (param *Param) Name() string

Name gets parameter field name

func (*Param) Raw

func (param *Param) Raw() interface{}

Raw gets the param's original value

type Params

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

Params struct handler information for binding and validation

type StructArgsBinder

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

StructArgsBinder a plugin that binds and validates structure type parameters.

func NewStructArgsBinder

func NewStructArgsBinder(fn ErrorFunc) *StructArgsBinder

NewStructArgsBinder creates a plugin that binds and validates structure type parameters.

func (*StructArgsBinder) Name

func (*StructArgsBinder) Name() string

Name returns the plugin name.

func (*StructArgsBinder) PostReadCallBody

func (s *StructArgsBinder) PostReadCallBody(ctx tp.ReadCtx) *tp.Status

PostReadCallBody binds and validates the registered struct handler.

func (*StructArgsBinder) PostReg

func (s *StructArgsBinder) PostReg(h *tp.Handler) error

PostReg preprocessing struct handler.

func (*StructArgsBinder) SetErrorFunc

func (s *StructArgsBinder) SetErrorFunc(fn ErrorFunc)

SetErrorFunc sets the binding or balidating error function. NOTE: If fn=nil, set as default.