plugin: introduce plugin framework (#8788)

cmd/pluginpkg/pluginpkg.go

@@ -23,6 +23,7 @@ import (
 	"os/exec"
 	"path"
 	"path/filepath"
+	"strings"
 	"text/template"
 	"time"
 
@@ -98,6 +99,10 @@ func main() {
 	manifest["buildTime"] = time.Now().String()
 
 	pluginName := manifest["name"].(string)
+	if strings.Contains(pluginName, "-") {
+		log.Printf("plugin name should not contain '-'\n")
+		os.Exit(1)
+	}
 	if pluginName != filepath.Base(pkgDir) {
 		log.Printf("plugin package must be same with plugin name in manifest file\n")
 		os.Exit(1)

go.mod

@@ -48,7 +48,7 @@ require (
 	github.com/pingcap/gofail v0.0.0-20181217135706-6a951c1e42c3
 	github.com/pingcap/goleveldb v0.0.0-20171020122428-b9ff6c35079e
 	github.com/pingcap/kvproto v0.0.0-20181203065228-c14302da291c
-	github.com/pingcap/parser v0.0.0-20190108104142-35fab0be7fca
+	github.com/pingcap/parser v0.0.0-20190114015132-c5c6ec2eb454
 	github.com/pingcap/pd v2.1.0-rc.4+incompatible
 	github.com/pingcap/tidb-tools v2.1.3-0.20190104033906-883b07a04a73+incompatible
 	github.com/pingcap/tipb v0.0.0-20181012112600-11e33c750323

go.sum

@@ -110,8 +110,8 @@ github.com/pingcap/goleveldb v0.0.0-20171020122428-b9ff6c35079e h1:P73/4dPCL96rG
 github.com/pingcap/goleveldb v0.0.0-20171020122428-b9ff6c35079e/go.mod h1:O17XtbryoCJhkKGbT62+L2OlrniwqiGLSqrmdHCMzZw=
 github.com/pingcap/kvproto v0.0.0-20181203065228-c14302da291c h1:Qf5St5XGwKgKQLar9lEXoeO0hJMVaFBj3JqvFguWtVg=
 github.com/pingcap/kvproto v0.0.0-20181203065228-c14302da291c/go.mod h1:Ja9XPjot9q4/3JyCZodnWDGNXt4pKemhIYCvVJM7P24=
-github.com/pingcap/parser v0.0.0-20190108104142-35fab0be7fca h1:BIk063GpkHOJzR4Bp9I8xfsjp3nSvElvhIUjDgmInoo=
-github.com/pingcap/parser v0.0.0-20190108104142-35fab0be7fca/go.mod h1:1FNvfp9+J0wvc4kl8eGNh7Rqrxveg15jJoWo/a0uHwA=
+github.com/pingcap/parser v0.0.0-20190114015132-c5c6ec2eb454 h1:8wqFaAY5HLvDH35UkzMhtuxb4Q0fk6/yeiOscfOmMpo=
+github.com/pingcap/parser v0.0.0-20190114015132-c5c6ec2eb454/go.mod h1:1FNvfp9+J0wvc4kl8eGNh7Rqrxveg15jJoWo/a0uHwA=
 github.com/pingcap/pd v2.1.0-rc.4+incompatible h1:/buwGk04aHO5odk/+O8ZOXGs4qkUjYTJ2UpCJXna8NE=
 github.com/pingcap/pd v2.1.0-rc.4+incompatible/go.mod h1:nD3+EoYes4+aNNODO99ES59V83MZSI+dFbhyr667a0E=
 github.com/pingcap/tidb-tools v2.1.3-0.20190104033906-883b07a04a73+incompatible h1:Ba48wwPwPq5hd1kkQpgua49dqB5cthC2zXVo7fUUDec=

plugin/conn_ip_example/conn_ip_example.go

@@ -0,0 +1,49 @@
+// Copyright 2019 PingCAP, Inc.
+//
+// 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,
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package main
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/pingcap/tidb/plugin"
+	"github.com/pingcap/tidb/sessionctx/variable"
+)
+
+// Validate implements TiDB plugin's Validate SPI.
+func Validate(ctx context.Context, m *plugin.Manifest) error {
+	fmt.Println("conn_ip_example validate called")
+	return nil
+}
+
+// OnInit implements TiDB plugin's OnInit SPI.
+func OnInit(ctx context.Context, manifest *plugin.Manifest) error {
+	fmt.Println("conn_ip_example init called")
+	fmt.Println("read cfg in init", manifest.SysVars["conn_ip_example_test_variable"].Value)
+	return nil
+}
+
+// OnShutdown implements TiDB plugin's OnShutdown SPI.
+func OnShutdown(ctx context.Context, manifest *plugin.Manifest) error {
+	fmt.Println("conn_ip_examples hutdown called")
+	return nil
+}
+
+// NotifyEvent implements TiDB Audit plugin's NotifyEvent SPI.
+func NotifyEvent(ctx context.Context) error {
+	fmt.Println("conn_ip_example notifiy called")
+	fmt.Println("variable test: ", variable.GetSysVar("conn_ip_example_test_variable").Value)
+	fmt.Printf("new connection by %s\n", ctx.Value("ip"))
+	return nil
+}

plugin/conn_ip_example/conn_ip_example_test.go

@@ -0,0 +1,61 @@
+// Copyright 2019 PingCAP, Inc.
+//
+// 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,
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package main_test
+
+import (
+	"context"
+
+	"github.com/pingcap/tidb/plugin"
+	"github.com/pingcap/tidb/sessionctx/variable"
+)
+
+func Example_LoadRunShutdownPlugin() {
+	ctx := context.Background()
+	var pluginVarNames []string
+	cfg := plugin.Config{
+		Plugins:        []string{"conn_ip_example-1"},
+		PluginDir:      "/home/robi/Code/go/src/github.com/pingcap/tidb/plugin/conn_ip_example",
+		GlobalSysVar:   &variable.SysVars,
+		PluginVarNames: &pluginVarNames,
+	}
+
+	err := plugin.Init(ctx, cfg)
+	if err != nil {
+		panic(err)
+	}
+
+	ps := plugin.GetByKind(plugin.Audit)
+	for _, auditPlugin := range ps {
+		if auditPlugin.State != plugin.Ready {
+			continue
+		}
+		plugin.DeclareAuditManifest(auditPlugin.Manifest).NotifyEvent(context.Background(), nil)
+	}
+
+	err = plugin.Reload(ctx, cfg, plugin.ID("conn_ip_example-2"))
+	if err != nil {
+		panic(err)
+	}
+
+	for _, auditPlugin := range plugin.GetByKind(plugin.Audit) {
+		if auditPlugin.State != plugin.Ready {
+			continue
+		}
+		plugin.DeclareAuditManifest(auditPlugin.Manifest).NotifyEvent(
+			context.WithValue(context.Background(), "ip", "1.1.1.2"), nil,
+		)
+	}
+
+	plugin.Shutdown(context.Background())
+}

plugin/conn_ip_example/manifest.toml

@@ -0,0 +1,15 @@
+name = "conn_ip_example"
+kind = "Audit"
+description = "just a test"
+version = "1"
+license = ""
+sysVars = [
+    {name="conn_ip_example_test_variable", scope="Global", value="2"},
+    {name="conn_ip_example_test_variable2", scope="Session", value="2"},
+]
+validate = "Validate"
+onInit = "OnInit"
+onShutdown = "OnShutdown"
+export = [
+    {extPoint="NotifyEvent", impl="NotifyEvent"}
+]

plugin/const.go

@@ -0,0 +1,70 @@
+// Copyright 2019 PingCAP, Inc.
+//
+// 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,
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package plugin
+
+// Kind presents the kind of plugin.
+type Kind uint8
+
+const (
+	// Audit indicates it is a Audit plugin.
+	Audit Kind = 1 + iota
+	// Authentication indicate it is a Authentication plugin.
+	Authentication
+	// Schema indicate a plugin that can change TiDB schema.
+	Schema
+	// Daemon indicate a plugin that can run as daemon task.
+	Daemon
+)
+
+func (k Kind) String() (str string) {
+	switch k {
+	case Audit:
+		str = "Audit"
+	case Authentication:
+		str = "Authentication"
+	case Schema:
+		str = "Schema"
+	case Daemon:
+		str = "Daemon"
+	}
+	return
+}
+
+// State present the state of plugin.
+type State uint8
+
+const (
+	// Uninitialized indicates plugin is uninitialized.
+	Uninitialized State = iota
+	// Ready indicates plugin is ready to work.
+	Ready
+	// Dying indicates plugin will be close soon.
+	Dying
+	// Disable indicate plugin is disabled.
+	Disable
+)
+
+func (s State) String() (str string) {
+	switch s {
+	case Uninitialized:
+		str = "Uninitialized"
+	case Ready:
+		str = "Ready"
+	case Dying:
+		str = "Dying"
+	case Disable:
+		str = "Disable"
+	}
+	return
+}

plugin/errors.go

@@ -0,0 +1,50 @@
+// Copyright 2019 PingCAP, Inc.
+//
+// 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,
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package plugin
+
+import (
+	"github.com/pingcap/parser/mysql"
+	"github.com/pingcap/parser/terror"
+)
+
+var (
+	errInvalidPluginID            = createPluginError(mysql.ErrInvalidPluginID)
+	errInvalidPluginManifest      = createPluginError(mysql.ErrInvalidPluginManifest)
+	errInvalidPluginName          = createPluginError(mysql.ErrInvalidPluginName)
+	errInvalidPluginVersion       = createPluginError(mysql.ErrInvalidPluginVersion)
+	errDuplicatePlugin            = createPluginError(mysql.ErrDuplicatePlugin)
+	errInvalidPluginSysVarName    = createPluginError(mysql.ErrInvalidPluginSysVarName)
+	errRequireVersionCheckFail    = createPluginError(mysql.ErrRequireVersionCheckFail)
+	errUnsupportedReloadPlugin    = createPluginError(mysql.ErrUnsupportedReloadPlugin)
+	errUnsupportedReloadPluginVar = createPluginError(mysql.ErrUnsupportedReloadPluginVar)
+)
+
+func createPluginError(code terror.ErrCode) *terror.Error {
+	return terror.ClassPlugin.New(code, mysql.MySQLErrName[uint16(code)])
+}
+
+func init() {
+	pluginMySQLErrCodes := map[terror.ErrCode]uint16{
+		mysql.ErrInvalidPluginID:            mysql.ErrInvalidPluginID,
+		mysql.ErrInvalidPluginManifest:      mysql.ErrInvalidPluginManifest,
+		mysql.ErrInvalidPluginName:          mysql.ErrInvalidPluginName,
+		mysql.ErrInvalidPluginVersion:       mysql.ErrInvalidPluginVersion,
+		mysql.ErrDuplicatePlugin:            mysql.ErrDuplicatePlugin,
+		mysql.ErrInvalidPluginSysVarName:    mysql.ErrInvalidPluginSysVarName,
+		mysql.ErrRequireVersionCheckFail:    mysql.ErrRequireVersionCheckFail,
+		mysql.ErrUnsupportedReloadPlugin:    mysql.ErrUnsupportedReloadPlugin,
+		mysql.ErrUnsupportedReloadPluginVar: mysql.ErrUnsupportedReloadPluginVar,
+	}
+	terror.ErrClassToMySQLCodes[terror.ClassPlugin] = pluginMySQLErrCodes
+}

plugin/helper.go

@@ -0,0 +1,54 @@
+// Copyright 2019 PingCAP, Inc.
+//
+// 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,
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package plugin
+
+import (
+	"strings"
+	"unsafe"
+)
+
+// DeclareAuditManifest declares manifest as AuditManifest.
+func DeclareAuditManifest(m *Manifest) *AuditManifest {
+	return (*AuditManifest)(unsafe.Pointer(m))
+}
+
+// DeclareAuthenticationManifest declares manifest as AuthenticationManifest.
+func DeclareAuthenticationManifest(m *Manifest) *AuthenticationManifest {
+	return (*AuthenticationManifest)(unsafe.Pointer(m))
+}
+
+// DeclareSchemaManifest declares manifest as SchemaManifest.
+func DeclareSchemaManifest(m *Manifest) *SchemaManifest {
+	return (*SchemaManifest)(unsafe.Pointer(m))
+}
+
+// DeclareDaemonManifest declares manifest as DaemonManifest.
+func DeclareDaemonManifest(m *Manifest) *DaemonManifest {
+	return (*DaemonManifest)(unsafe.Pointer(m))
+}
+
+// ID present plugin identity.
+type ID string
+
+// Decode decodes a plugin id into name, version parts.
+func (n ID) Decode() (name string, version string, err error) {
+	splits := strings.Split(string(n), "-")
+	if len(splits) != 2 {
+		err = errInvalidPluginID.GenWithStackByArgs(string(n))
+		return
+	}
+	name = splits[0]
+	version = splits[1]
+	return
+}