Merge pull request #2 from krakend/plugin-examples

Add README and some minor changes to plugin examples

plugins/README.md

@@ -0,0 +1,39 @@
+# KrakenD Plugin Examples
+
+This repository contains examples demonstrating how to build and inject custom plugins into the KrakenD API Gateway. These examples cover three types of plugins: HTTP Client, Handler/Server, and Request/Response Modifier.
+
+## Overview
+
+The repository is structured into three main directories, each containing a specific type of plugin:
+
+### 1. Client Plugin
+
+The client plugin demonstrates how to create a custom HTTP client that can be integrated into KrakenD. The plugin adds custom logic for handling HTTP requests.
+
+**More details and instructions can be found in the `client` directory.**
+
+### 2. Handler/Server Plugin
+
+The handler/server plugin shows how to create a custom HTTP handler. This plugin allows you to add custom logic to process HTTP requests before they reach the backend.
+
+**More details and instructions can be found in the `handler` directory.**
+
+### 3. Request/Response Modifier Plugin
+
+The request/response modifier plugin illustrates how to create custom request and response modifiers. This plugin can modify the request before it is sent to the backend and the response before it is returned to the client.
+
+**More details and instructions can be found in the `modifier` directory.**
+
+## Building the Plugins
+
+Each plugin directory contains the necessary code and a `Makefile` for building the plugin using Docker. Follow the instructions in each directory's README to build and integrate the plugins into your KrakenD setup.
+
+## Documentation
+
+For more information on extending KrakenD with plugins, refer to the official documentation:
+
+- [HTTP Client Plugins](https://www.krakend.io/docs/extending/http-client-plugins/)
+- [HTTP Server Plugins](https://www.krakend.io/docs/extending/http-server-plugins/)
+- [Request/Response Modifier Plugins](https://www.krakend.io/docs/extending/plugin-modifiers/)
+
+This repository aims to provide a starting point for creating your own plugins to extend the functionality of the KrakenD API Gateway. Happy coding!

plugins/client/Makefile

@@ -1,6 +1,6 @@
 # KrakenD Version
 VERSION := latest
-PLUGINAME := plugin
+PLUGINAME := plugins/client
 
 # Build KrakenD plugin using the KrakenD docker builder (for running inside docker)
 amd64:

plugins/client/README.md

@@ -0,0 +1,127 @@
+# KrakenD - HTTP Client Plugin Example
+
+This repository provides an example of how to build and inject a Client Plugin into the KrakenD API Gateway. Follow the steps below to understand how to set up and use the client plugin.
+
+## Overview
+
+The client plugin, named `my-client-plugin`, demonstrates how to create a custom HTTP client that can be integrated into KrakenD. The plugin replaces the default HTTP client by adding custom logic before and after the request is processed.
+
+## File Structure
+
+- `client.go`: The main plugin code that implements the `RegisterClient` interface.
+- `go.mod`: The Go module file.
+- `Makefile`: Instructions for building the plugin using Docker.
+
+## Prerequisites
+
+- [Go](https://golang.org/dl/)
+- Docker
+- KrakenD API Gateway (version 2.x)
+
+## Building the Plugin
+
+You should build the plugin using the KrakenD Docker builder image. The `Makefile` includes targets for different architectures.
+
+### Steps
+
+1. **Clone the Repository**:
+
+    ```bash
+    git clone https://github.com/krakend/examples.git
+    cd examples/plugins/client
+    ```
+
+2. **Build for Different Architectures**:
+   - For **amd64**:
+
+       ```bash
+       make amd64
+       ```
+
+   - For **arm64**:
+
+       ```bash
+       make arm64
+       ```
+
+   - For **linux_amd64** (non-docker):
+
+       ```bash
+       make linux_amd64
+       ```
+
+   - For **linux_arm64** (non-docker):
+
+       ```bash
+       make linux_arm64
+       ```
+
+
+## Plugin Configuration
+
+To use the plugin in your KrakenD configuration, add it under the `extra_config` section of your `krakend.json` file.
+
+### Example Configuration
+
+```json
+{
+  "version": 3,
+  "plugin": {
+    "pattern": ".so",
+    "folder": "/etc/krakend/plugins"
+  },
+  "host": ["http://localhost:8080/"],
+  "debug_endpoint": true,
+  "endpoints": [
+    {
+      "endpoint": "/example",
+      "backend": [
+        {
+          "url_pattern": "/__debug/",
+          "extra_config": {
+            "plugin/http-client": {
+              "name": "my-client-plugin",
+              "my-client-plugin": {
+                "option": "/some-path"
+              }
+            }
+          }
+        }
+      ]
+    }
+  ]
+}
+
+```
+
+## Logger Interface
+
+The plugin supports a logger interface to help with debugging and logging messages.
+
+### Logger Methods
+
+- `Debug(v ...interface{})`
+- `Info(v ...interface{})`
+- `Warning(v ...interface{})`
+- `Error(v ...interface{})`
+- `Critical(v ...interface{})`
+- `Fatal(v ...interface{})`
+
+## Custom Logic
+
+The `my-client-plugin` adds custom logic by wrapping the default HTTP client. It logs the request details and copies headers, status codes, and body from the backend response to the client response.
+
+## Usage
+
+1. **Build the plugin** using the appropriate make target. The plugin will be generated under the `plugins` folder.
+2. **Test your KrakenD using Docker**, for instance:
+```bash
+docker run --rm -it --name krakend -p 8080:8080 -v "$PWD:/etc/krakend" devopsfaith/krakend
+```
+3. **Send an example call**
+```bash
+curl -iG 'http://localhost:8080/example'
+```
+
+
+For more details on client plugins and extending KrakenD, refer to the [official documentation](https://www.krakend.io/docs/extending/http-client-plugins/).

plugins/client/client.go

@@ -107,7 +107,7 @@ func (registerer) RegisterLogger(v interface{}) {
 		return
 	}
 	logger = l
-	logger.Debug(fmt.Sprintf("[PLUGIN: %s] Logger loaded", pluginName))
+	logger.Debug(fmt.Sprintf("[PLUGIN: %s] Example client plugin loaded", pluginName))
 }
 
 type Logger interface {

plugins/client/krakend.json

@@ -0,0 +1,27 @@
+{
+  "version": 3,
+  "plugin": {
+    "pattern": ".so",
+    "folder": "/etc/krakend/plugins"
+  },
+  "host": ["http://localhost:8080/"],
+  "debug_endpoint": true,
+  "endpoints": [
+    {
+      "endpoint": "/example",
+      "backend": [
+        {
+          "url_pattern": "/__debug/",
+          "extra_config": {
+            "plugin/http-client": {
+              "name": "my-client-plugin",
+              "my-client-plugin": {
+                "option": "/some-path"
+              }
+            }
+          }
+        }
+      ]
+    }
+  ]
+}

plugins/handler/Makefile

@@ -1,6 +1,6 @@
 # KrakenD Version
 VERSION := latest
-PLUGINAME := plugin
+PLUGINAME := plugins/handler
 
 # Build KrakenD plugin using the KrakenD docker builder (for running inside docker)
 amd64:

plugins/handler/README.md

@@ -0,0 +1,126 @@
+# KrakenD - HTTP Handler Plugin Example
+
+This repository provides an example of how to build and inject a Handler Plugin into the KrakenD API Gateway. Follow the steps below to understand how to set up and use the handler plugin.
+
+## Overview
+
+The handler plugin, named `my-handler-plugin`, demonstrates how to create a custom HTTP handler that can be integrated into KrakenD. The plugin replaces the default HTTP handler by adding custom logic before and after the request is processed.
+
+## File Structure
+
+- `handler.go`: The main plugin code that implements the `RegisterHandler` interface.
+- `go.mod`: The Go module file.
+- `Makefile`: Instructions for building the plugin using Docker.
+
+## Prerequisites
+
+- [Go](https://golang.org/dl/)
+- Docker
+- KrakenD API Gateway (version 2.x)
+
+## Building the Plugin
+
+You should build the plugin using the KrakenD Docker builder image. The `Makefile` includes targets for different architectures.
+
+### Steps
+
+1. **Clone the Repository**:
+
+    ```bash
+    git clone https://github.com/krakend/examples.git
+    cd examples/plugins/handler
+    ```
+
+2. **Build for Different Architectures**:
+    - For **amd64**:
+
+        ```bash
+        make amd64
+        ```
+
+    - For **arm64**:
+
+        ```bash
+        make arm64
+        ```
+
+    - For **linux_amd64** (non-docker):
+
+        ```bash
+        make linux_amd64
+        ```
+
+    - For **linux_arm64** (non-docker):
+
+        ```bash
+        make linux_arm64
+        ```
+
+
+## Plugin Configuration
+
+To use the plugin in your KrakenD configuration, add it under the `extra_config` section of your `krakend.json` file.
+
+### Example Configuration
+
+```json
+{
+   "version": 3,
+   "plugin": {
+      "pattern": ".so",
+      "folder": "/etc/krakend/plugins"
+   },
+   "host": ["http://localhost:8080/"],
+   "debug_endpoint": true,
+   "endpoints": [
+      {
+         "endpoint": "/example",
+         "backend": [
+            {
+               "url_pattern": "/__debug/"
+            }
+         ]
+      }
+   ],
+   "extra_config": {
+      "plugin/http-server": {
+         "name": ["my-handler-plugin"],
+         "my-handler-plugin": {
+            "someOption": "some-value"
+         }
+      }
+   }
+}
+
+```
+
+## Logger Interface
+
+The plugin supports a logger interface to help with debugging and logging messages.
+
+### Logger Methods
+
+- `Debug(v ...interface{})`
+- `Info(v ...interface{})`
+- `Warning(v ...interface{})`
+- `Error(v ...interface{})`
+- `Critical(v ...interface{})`
+- `Fatal(v ...interface{})`
+
+## Custom Logic
+
+The `my-handler-plugin` adds custom logic by wrapping the default HTTP handler. It logs the configuration option and then processes the request using the default handler.
+
+## Usage
+
+1. **Build the plugin** using the appropriate make target. The plugin will be generated under the `plugins` folder.
+2. **Test your KrakenD using Docker**, for instance:
+```bash
+docker run --rm -it --name krakend -p 8080:8080 -v "$PWD:/etc/krakend" devopsfaith/krakend
+```
+3. **Send an example call**
+```bash
+curl -iG 'http://localhost:8080/example'
+```
+
+For more details on handler plugins and extending KrakenD, refer to the [official documentation](https://www.krakend.io/docs/extending/http-server-plugins/).

plugins/handler/handler.go

@@ -86,7 +86,7 @@ func (registerer) RegisterLogger(v interface{}) {
 		return
 	}
 	logger = l
-	logger.Debug(fmt.Sprintf("[PLUGIN: %s] Logger loaded", pluginName))
+	logger.Debug(fmt.Sprintf("[PLUGIN: %s] Example handler plugin loaded", pluginName))
 }
 
 type Logger interface {

plugins/handler/krakend.json

@@ -0,0 +1,27 @@
+{
+  "version": 3,
+  "plugin": {
+    "pattern": ".so",
+    "folder": "/etc/krakend/plugins"
+  },
+  "host": ["http://localhost:8080/"],
+  "debug_endpoint": true,
+  "endpoints": [
+    {
+      "endpoint": "/example",
+      "backend": [
+        {
+          "url_pattern": "/__debug/"
+        }
+      ]
+    }
+  ],
+  "extra_config": {
+    "plugin/http-server": {
+      "name": ["my-handler-plugin"],
+      "my-handler-plugin": {
+        "option": "some-value"
+      }
+    }
+  }
+}

plugins/modifier/Makefile

@@ -1,6 +1,6 @@
 # KrakenD Version
 VERSION := latest
-PLUGINAME := plugin
+PLUGINAME := plugins/modifier
 
 # Build KrakenD plugin using the KrakenD docker builder (for running inside docker)
 amd64: