[trafficcontrol] 05/08: Add TO Go readme

[ne...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

neuman pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficcontrol.git

commit 19510fd4c8ef8b8787666f5254af6f72690c2f7a
Author: Robert Butts <ro...@apache.org>
AuthorDate: Mon Oct 1 13:18:21 2018 -0600

    Add TO Go readme
    
    As requested on the mailing list:
    https://lists.apache.org/thread.html/3b1386a5cb5dc0ba1d89931781668a16f0ae99aabf5662c332b40605@%3Cdev.trafficcontrol.apache.org%3E
---
 traffic_ops/traffic_ops_golang/plugin/README.md | 74 +++++++++++++++++++++++++
 1 file changed, 74 insertions(+)

diff --git a/traffic_ops/traffic_ops_golang/plugin/README.md b/traffic_ops/traffic_ops_golang/plugin/README.md
new file mode 100644
index 0000000..820d2ad
--- /dev/null
+++ b/traffic_ops/traffic_ops_golang/plugin/README.md
@@ -0,0 +1,74 @@
+<!--
+    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.
+-->
+
+# Adding a Plugin
+
+To add a plugin, create a new `.go` file in the `traffic_ops_golang/plugin` directory. This file should have a unique name, to avoid conflicts. Consider prefixing it with your company name, website, or a UUID.
+
+The filename, sans `.go`, is the name of your plugin, and will be the key used for configuration in the remap file. For example, if your file is `f49e54fc-fd17-4e1c-92c6-67028fde8504-hello-world.go`, the name of your plugin is `f49e54fc-fd17-4e1c-92c6-67028fde8504-hello-world`.
+
+Plugins are registered via calls to `AddPlugin` inside an `init` function in the plugin's file.
+
+The `Funcs` object contains functions for each hook, as well as a load function for loading configuration from the remap file. The current hooks are `load`, `startup`, and `onRequest`. If your plugin does not use a hook, it may be nil.
+
+* `load` is called when the application starts, is given config data, and must return the loaded configuration object.
+
+* `startup` is called when the application starts.
+
+* `onRequest` is called immediately when a request is received. It returns a boolean indicating whether to stop processing.
+
+The simplest example is the `hello_world` plugin. See `plugin/hello_world.go`.
+
+```go
+import (
+	"strings"
+)
+func init() {
+	AddPlugin(10000, Funcs{onRequest: hello})
+}
+const HelloPath = "/_hello"
+func hello(d OnRequestData) IsRequestHandled {
+	if !strings.HasPrefix(d.R.URL.Path, HelloPath) {
+		return RequestUnhandled
+	}
+	d.W.Header().Set("Content-Type", "text/plain")
+	d.W.Write([]byte("Hello, World!"))
+	return RequestHandled
+}
+```
+
+The plugin is initialized via `AddPlugin`, and its `hello` function is set as the `startup` hook. The `hello` function has the signature of `plugin.StartupFunc`.
+
+# Examples
+
+Example plugins are included in the `/plugin` directory
+
+*hello_world*: Example of a simple HTTP endpoint.
+*hello_config*: Example of loading and using config file data.
+*hello_shared_config*: Example of loading and using config data which is shared among all plugins.
+*hello_context*: Example of passing context data between hook functions.
+*hello_startup*: Example of running a plugin function when the application starts.
+
+# Glossary
+
+Definitions of terms used in this document.
+
+*Plugin*: A self-contained component whose code is executed when certain events in the main application occur.
+*Hook*: A plugin function which is called when a certain event happens in the main application.
+*Plugin Data*: Application data given to a plugin, as a function parameter passed to a hook function, including configuration data, running state, and HTTP request state.