Docs and fix: path rewrite flag (#190)

* update docs with instructions on how to use the path rewrite option

* rename rewrite_base to rewrite

* remove trailing slash trimming when setting rewrite option as some users will need to specify it and keep it in the resulting manifest

docs/ambassador2.md

@@ -17,6 +17,7 @@ Flags:
       --service.port int32                target Service port (default 80)
       --host string                       the Host header value to listen on
       --path.base string                  a base path for Service endpoints (default "/")
+      --path.rewrite string               rewrite your base path before forwarding to the upstream service
       --path.split                        force Kusk to generate a separate Mapping for each operation
       --path.trim_prefix string           a prefix to trim from the URL before forwarding to the upstream Service
       --rate_limits.burst uint32          request per second burst
@@ -42,6 +43,7 @@ To override settings on the path or HTTP method level, you are required to use t
 | Service Namespace       | --service.namespace        | service.namespace         | The namespace where the service named above resides (default value: default)                                       | ❌                             |
 | Service Port            | --service.port             | service.port              | Port the service is listening on (default value: 80)                                                               | ❌                             |
 | Path Base               | --path.base                | path.base                 | Prefix for your resource routes                                                                                    | ❌                             |
+| Path Rewrite            | --path.rewrite             | path.rewrite              | Rewrite your base path before forwarding to the upstream service                                                   | ❌                             |
 | Path Trim Prefix        | --path.trim_prefix         | path.trim_prefix          | Trim the specified prefix from URl before passing request onto service                                             | ❌                             |
 | Path split              | --path.split               | path.split                | Boolean; whether or not to force generator to generate a mapping for each path                                     | ❌                             |
 | Host                    | --host                     | host                      | The value to set the host field to in the Mapping resource                                                         | ✅                             |
@@ -69,22 +71,20 @@ To override settings on the path or HTTP method level, you are required to use t
 helm repo add datawire https://www.getambassador.io
 helm repo update
 
-# Create Namespace and Install:
-helm install -n ambassador --create-namespace \
-        edge-stack --devel \
-        datawire/edge-stack && \
-    kubectl rollout status  -n ambassador deployment/edge-stack -w
+kubectl create namespace emissary && \
+helm install emissary-ingress --devel --namespace emissary datawire/emissary-ingress && \
+kubectl -n emissary wait --for condition=available --timeout=90s deploy -lapp.kubernetes.io/instance=emissary-ingress
 ```
 
 ### Create the AmbassadorListeners
 ```
 kubectl apply -f - <<EOF
 ---
 apiVersion: x.getambassador.io/v3alpha1
-kind: AmbassadorListener
+kind: Listener
 metadata:
   name: edge-stack-listener-8080
-  namespace: ambassador
+  namespace: emissary
 spec:
   port: 8080
   protocol: HTTP
@@ -94,10 +94,10 @@ spec:
       from: ALL
 ---
 apiVersion: x.getambassador.io/v3alpha1
-kind: AmbassadorListener
+kind: Listener
 metadata:
   name: edge-stack-listener-8443
-  namespace: ambassador
+  namespace: emissary
 spec:
   port: 8443
   protocol: HTTPS
@@ -113,7 +113,7 @@ EOF
 cat <<EOF | kubectl apply -f -
 ---
 apiVersion: x.getambassador.io/v3alpha1
-kind: AmbassadorHost
+kind: Host
 metadata:
   name: my-host
   namespace: ambassador
@@ -326,6 +326,72 @@ Or go to your web browser
 
 ---
 
+## Base Path and Rewrite
+Setting the Base path option allows your service to be identified with the base path acting as a prefix.
+
+Setting the rewrite option will instruct ambassador to rewrite the base path before sending the request to the upstream service
+
+When no rewrite or trim prefix is specified, the rewrite option will default to `""`. 
+
+**note** If you want the default ambassador behaviour for rewrites, set the rewrite option to `/`
+**note** `trim_prefix` takes precedence over rewrite. If both are defined, `trim_prefix` will take effect and `rewrite` will be ignored.
+
+### CLI Flags
+
+```shell
+kusk ambassador2 -i examples/booksapp/booksapp.yaml \
+--namespace booksapp \
+--host "*" \
+--service.name webapp \
+--service.port 7000 \
+--service.namespace booksapp \
+--path.base /my-app \
+--path.rewrite /my-other-app
+```
+
+### OpenAPI Specification
+
+```yaml
+openapi: 3.0.1
+x-kusk:
+  namespace: booksapp
+  host: "*"
+  service:
+    name: webapp
+    namespace: booksapp
+    port: 7000
+  path:
+    base: /my-app
+    rewrite: /my-other-app
+paths:
+  /:
+    get: {}
+...
+```
+
+### Sample Output
+
+```yaml
+---
+apiVersion: x.getambassador.io/v3alpha1
+kind: Mapping
+metadata:
+  name: booksapp
+  namespace: booksapp
+spec:
+  prefix: "/my-app"
+  hostname: '*'
+  service: booksapp.booksapp:7000
+  rewrite: "/my-other-app"
+```
+
+### Test
+`curl -Lki https://localhost:8443/my-app/`
+
+Or go to your web browser
+
+**Note** the trailing `/` is mandatory.
+
 ## Setting timeouts
 
 kusk allows for setting both idle and request timeouts via flags or the x-kusk OpenAPI extension

generators/ambassador/ambassador.go

@@ -122,8 +122,8 @@ func (a *AbstractGenerator) Generate(opts *options.Options, spec *openapi3.T) (s
 				mappingName := generateMappingName(opts.Service.Name, method, path, operation)
 
 				var pathRewrite string
-				if opts.Path.RewriteBase != "" {
-					pathRewrite = strings.TrimSuffix(opts.Path.RewriteBase, "/") + mappingPath
+				if opts.Path.Rewrite != "" {
+					pathRewrite = strings.TrimSuffix(opts.Path.Rewrite, "/") + mappingPath
 				}
 
 				op := mappingTemplateData{
@@ -220,7 +220,7 @@ func (a *AbstractGenerator) Generate(opts *options.Options, spec *openapi3.T) (s
 			ServiceURL:       serviceURL,
 			BasePath:         opts.Path.Base,
 			TrimPrefix:       opts.Path.TrimPrefix,
-			PathRewrite:      strings.TrimSuffix(opts.Path.RewriteBase, "/"),
+			PathRewrite:      opts.Path.Rewrite,
 			RequestTimeout:   opts.Timeouts.RequestTimeout * 1000,
 			IdleTimeout:      opts.Timeouts.IdleTimeout * 1000,
 			Host:             opts.Host,

generators/ambassador/v1/ambassador_test.go

@@ -1756,7 +1756,7 @@ paths:
 				Host:      "*",
 				Path: options.PathOptions{
 					Base:        "/my-bookstore",
-					RewriteBase: "/bookstore/",
+					Rewrite: "/bookstore/",
 				},
 				Service: options.ServiceOptions{
 					Namespace: "booksapp",
@@ -1775,7 +1775,7 @@ spec:
   prefix: "/my-bookstore"
   host: *
   service: webapp.booksapp:7000
-  rewrite: "/bookstore"
+  rewrite: "/bookstore/"
 `,
 		},
 		{
@@ -1819,7 +1819,7 @@ paths:
 				Host:      "*",
 				Path: options.PathOptions{
 					Base:        "/my-bookstore/",
-					RewriteBase: "/bookstore/",
+					Rewrite: "/bookstore/",
 				},
 				Service: options.ServiceOptions{
 					Namespace: "booksapp",

generators/ambassador/v2/ambassador_test.go

@@ -1838,7 +1838,7 @@ paths:
 				Host:      "*",
 				Path: options.PathOptions{
 					Base:        "/my-bookstore",
-					RewriteBase: "/bookstore/",
+					Rewrite: "/bookstore/",
 				},
 				Service: options.ServiceOptions{
 					Namespace: "booksapp",
@@ -1857,7 +1857,7 @@ spec:
   prefix: "/my-bookstore"
   hostname: '*'
   service: webapp.booksapp:7000
-  rewrite: "/bookstore"
+  rewrite: "/bookstore/"
 `,
 		},
 		{
@@ -1901,7 +1901,7 @@ paths:
 				Host:      "*",
 				Path: options.PathOptions{
 					Base:        "/my-bookstore/",
-					RewriteBase: "/bookstore/",
+					Rewrite: "/bookstore/",
 				},
 				Service: options.ServiceOptions{
 					Namespace: "booksapp",

options/path.go

@@ -1,7 +1,7 @@
 package options
 
 import (
-	"github.com/go-ozzo/ozzo-validation/v4"
+	validation "github.com/go-ozzo/ozzo-validation/v4"
 )
 
 type PathOptions struct {
@@ -15,9 +15,9 @@ type PathOptions struct {
 	// is "/api/v3/pets".
 	TrimPrefix string `yaml:"trim_prefix,omitempty" json:"trim_prefix,omitempty"`
 
-	// RewriteBase is the rewrite value that should replace the Base path before being forwarded to the
+	// Rewrite is the rewrite value that should replace the Base path before being forwarded to the
 	// upstream service
-	RewriteBase string `yaml:"rewrite_base,omitempty" json:"rewrite_base,omitempty"`
+	Rewrite string `yaml:"rewrite,omitempty" json:"rewrite,omitempty"`
 
 	// Split forces Kusk to generate a separate resource for each Path or Operation, where appropriate.
 	Split bool `yaml:"split,omitempty" json:"split,omitempty"`