Init

Author: akarashchuk

.editorconfig

@@ -0,0 +1,14 @@
+# editorconfig.org
+
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false

.github/workflows/build.yml

@@ -0,0 +1,28 @@
+name: build
+
+on:
+  push:
+    branches-ignore:
+      - master
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Setup Go
+        uses: actions/setup-go@v4
+        with:
+          go-version: '1.25.7'
+          cache: false
+
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Golangci Lint
+        uses: golangci/golangci-lint-action@v9
+
+      - name: Run tests
+        run: go test -race
+
+      - name: Check plugin
+        run: docker run --rm -v "$PWD/go.sum:/app/go.sum" -w /app krakend:2.13.1 krakend check-plugin -g 1.25.7 -l "MUSL-1.2.5_(alpine-3.23.3)" -s ./go.sum

.github/workflows/release.yml

@@ -0,0 +1,60 @@
+name: release
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Setup Go
+        uses: actions/setup-go@v4
+        with:
+          go-version: '1.25.7'
+          cache: false
+
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Golangci Lint
+        uses: golangci/golangci-lint-action@v9
+
+      - name: Run tests
+        run: go test -race
+
+      - name: Build project
+        run: |
+          docker run --rm -v "$PWD:/app" -w /app krakend/builder:2.13.1 go build -buildmode=plugin -o krakend-fallback.so .
+          docker run --rm -v "$PWD/krakend-fallback.so:/app/krakend-fallback.so" -w /app krakend:2.13.1 krakend test-plugin -sc krakend-fallback.so
+          zip ./krakend-fallback.zip ./krakend-fallback.so
+
+      - name: Bump version and push tag
+        id: bump_tag
+        uses: anothrNick/github-tag-action@1.61.0
+        env:
+          GITHUB_TOKEN: ${{ secrets.JENKSY_GITHUB_TOKEN }}
+          WITH_V: true
+
+      - name: Create Release
+        id: create_release
+        uses: actions/create-release@v1.0.0
+        env:
+          GITHUB_TOKEN: ${{ secrets.JENKSY_GITHUB_TOKEN }}
+        with:
+          tag_name: ${{ steps.bump_tag.outputs.new_tag }}
+          release_name: Release ${{ steps.bump_tag.outputs.new_tag }}
+          draft: false
+          prerelease: false
+
+      - name: Upload Release Asset
+        id: upload-release-asset
+        uses: actions/upload-release-asset@v1.0.1
+        env:
+          GITHUB_TOKEN: ${{ secrets.JENKSY_GITHUB_TOKEN }}
+        with:
+          upload_url: ${{ steps.create_release.outputs.upload_url }}
+          asset_path: ./krakend-fallback.zip
+          asset_name: krakend-fallback.zip
+          asset_content_type: application/zip

README.md

@@ -1,2 +1,126 @@
-# krakend-fallback
-Server plugin that allows configuring route-based rules to enforce required response fields (returning an error if missing) and inject default values for absent fields.
+# Krakend Fallback
+
+Server plugin for **KrakenD** that allows configuring route-based rules to:
+
+- Enforce required response fields (returning an error if missing)
+- Inject default values for absent fields
+- Extract and propagate backend errors (`error_*`) when required fields are missing
+
+---
+
+## Overview
+
+The plugin works as a **server middleware**.
+
+For configured routes it:
+
+1. Intercepts the aggregated JSON response
+2. If response is not `2xx` or not JSON → passes it through untouched
+3. If JSON and successful:
+   - Injects default fields (if missing)
+   - Validates required fields
+   - If required field is missing:
+     - Looks for `error_*` keys in the response
+     - Sorts them
+     - Returns the first backend error
+     - If no backend error found → returns `500`
+
+---
+
+## Example KrakenD Configuration
+
+```json
+{
+  "plugin/http-server": {
+    "name": ["onliner/krakend-fallback"],
+    "onliner/krakend-fallback": {
+      "routes": [
+        {
+          "path": "/products/{product}/positions",
+          "required": ["product"],
+          "default": {
+            "positions": []
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+---
+
+## Route Configuration
+
+### `path`
+
+Path template using `{param}` syntax.
+
+Example:
+
+```
+/products/{product}/positions
+```
+
+---
+
+### `required`
+
+List of top-level JSON keys that must exist in the final aggregated response.
+
+If any key is missing:
+
+- Plugin searches for `error_*` fields
+- If found → returns the first backend error
+- If not found → returns `500 Internal Server Error`
+
+---
+
+### `default`
+
+Map of fields to inject if they are missing.
+
+Defaults are only applied for successful `2xx` JSON responses.
+
+Example:
+
+```json
+"default": {
+  "positions": [],
+  "shops": null
+}
+```
+
+---
+
+## Backend Error Format
+
+Backend errors must follow this structure inside the aggregated response:
+
+```json
+{
+  "error_1": {
+    "http_status_code": 500,
+    "http_body": "{\"message\":\"backend failed\"}",
+    "http_body_encoding": "application/json"
+  }
+}
+```
+
+### Fields
+
+- `http_status_code` – HTTP status to return
+- `http_body` – raw response body
+- `http_body_encoding` – Content-Type header (optional, defaults to `text/plain`)
+
+If multiple `error_*` keys exist, the plugin:
+
+1. Sorts them lexicographically
+2. Returns the first one
+
+## Notes
+
+- Plugin modifies only successful `2xx` JSON responses
+- Original headers are preserved when modifying response
+- `Content-Length` is recalculated when body is modified
+- Thread-safe and race-tested

backend_error.go

@@ -0,0 +1,56 @@
+package main
+
+import (
+	"bytes"
+	"io"
+	"net/http"
+	"sort"
+	"strings"
+
+	"github.com/mitchellh/mapstructure"
+)
+
+type BackendError struct {
+	Status   int    `mapstructure:"http_status_code"`
+	Body     string `mapstructure:"http_body"`
+	Encoding string `mapstructure:"http_body_encoding"`
+}
+
+func (e BackendError) ToResponse() *http.Response {
+	enc := e.Encoding
+	if enc == "" {
+		enc = "text/plain"
+	}
+	return &http.Response{
+		StatusCode:    e.Status,
+		Header:        http.Header{"Content-Type": []string{enc}},
+		Body:          io.NopCloser(bytes.NewBufferString(e.Body)),
+		ContentLength: int64(len(e.Body)),
+	}
+}
+
+func FindBackendError(body map[string]interface{}) (*http.Response, bool) {
+	keys := make([]string, 0, len(body))
+	for k := range body {
+		if strings.HasPrefix(k, "error_") {
+			keys = append(keys, k)
+		}
+	}
+	if len(keys) == 0 {
+		return nil, false
+	}
+
+	sort.Strings(keys)
+	v, ok := body[keys[0]]
+	if !ok {
+		return nil, false
+	}
+
+	var berr BackendError
+
+	if err := mapstructure.WeakDecode(v, &berr); err != nil {
+		return nil, false
+	}
+
+	return berr.ToResponse(), true
+}

backend_error_test.go

@@ -0,0 +1,83 @@
+package main
+
+import (
+	"io"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func readString(t *testing.T, rc io.ReadCloser) string {
+	t.Helper()
+	defer func(rc io.ReadCloser) {
+		err := rc.Close()
+		assert.NoError(t, err)
+	}(rc)
+	b, err := io.ReadAll(rc)
+	assert.NoError(t, err)
+	return string(b)
+}
+
+func TestFindBackendError_NoKeys(t *testing.T) {
+	resp, ok := FindBackendError(map[string]interface{}{
+		"product": map[string]interface{}{"id": 1},
+	})
+
+	assert.False(t, ok)
+	assert.Nil(t, resp)
+}
+
+func TestFindBackendError_PicksFirstSortedKey(t *testing.T) {
+	body := map[string]interface{}{
+		"error_2": map[string]interface{}{
+			"http_status_code":   502,
+			"http_body":          `{"message":"second"}`,
+			"http_body_encoding": "application/json",
+		},
+		"error_1": map[string]interface{}{
+			"http_status_code":   500,
+			"http_body":          `{"message":"first"}`,
+			"http_body_encoding": "application/json; charset=utf-8",
+		},
+		"product": map[string]interface{}{"id": 1},
+	}
+
+	resp, ok := FindBackendError(body)
+	assert.True(t, ok)
+	assert.NotNil(t, resp)
+
+	assert.Equal(t, 500, resp.StatusCode)
+	assert.Equal(t, "application/json; charset=utf-8", resp.Header.Get("Content-Type"))
+
+	gotBody := readString(t, resp.Body)
+	assert.Equal(t, `{"message":"first"}`, gotBody)
+	assert.Equal(t, int64(len(gotBody)), resp.ContentLength)
+}
+
+func TestFindBackendError_InvalidShape_ReturnsFalse(t *testing.T) {
+	body := map[string]interface{}{
+		"error_1": "not an object",
+	}
+
+	resp, ok := FindBackendError(body)
+	assert.False(t, ok)
+	assert.Nil(t, resp)
+}
+
+func TestFindBackendErrorMissingEncoding(t *testing.T) {
+	body := map[string]interface{}{
+		"error_1": map[string]interface{}{
+			"http_status_code": 503,
+			"http_body":        "service unavailable",
+		},
+	}
+
+	resp, ok := FindBackendError(body)
+	assert.True(t, ok)
+	assert.NotNil(t, resp)
+	assert.Equal(t, 503, resp.StatusCode)
+	assert.Equal(t, "text/plain", resp.Header.Get("Content-Type"))
+
+	got := readString(t, resp.Body)
+	assert.Equal(t, `service unavailable`, got)
+}