feat(javascript): add HttpResponse.rebuild()

Author: marle3003

docs/javascript-api/mokapi/eventhandler/httpresponse.md

@@ -9,13 +9,42 @@ description: HttpResponse is an object that is used to construct the HTTP respon
 It is used to define the outgoing HTTP response, including status code, headers,
 and response body.
 
+## Properties
+
 | Name       | Type   | Description                                                                  |
 |------------|--------|------------------------------------------------------------------------------|
 | statusCode | number | HTTP status code used to select the OpenAPI response definition              |
 | headers    | object | Response headers defined by the OpenAPI response header parameters           |
 | body       | string | Raw response body. Takes precedence over `data`                              |
 | data       | any    | Response data that will be encoded according to the OpenAPI response schema  |
 
+## Methods
+
+| Name                             | Description                  |
+|----------------------------------|------------------------------|
+| rebuild(statusCode, contentType) | Rebuilds the HTTP response   |
+
+## Example
+
+The following example demonstrates how to construct an HTTP response inside an
+HTTP event handler.
+
+```javascript
+import { on } from 'mokapi'
+
+export default function() {
+    on('http', (request, response) => {
+        response.statusCode = 200
+        response.headers = {
+            'Content-Type': 'application/json'
+        }
+        response.data = {
+            message: 'Hello World'
+        }
+    })
+}
+```
+
 ## Default Response Generation
 
 Mokapi automatically generates a valid HTTP response based on the OpenAPI
@@ -35,32 +64,75 @@ based on the schema defined for that status code.
 This behavior ensures that every response is valid according to the OpenAPI
 definition, even if the event handler does not explicitly modify the response.
 
-## Example
+## Body vs Data
 
-The following example demonstrates how to construct an HTTP response inside an
-HTTP event handler.
+Use body to return a raw response body without OpenAPI encoding and validating.
+
+Use data to return structured data that should be validated and encoded
+according to the OpenAPI response definition
+
+If both body and data are set, body takes precedence
+
+## Rebuilding a Response
+
+When changing the HTTP status code or content type, the existing response data
+and headers may no longer match the OpenAPI specification.
+
+To address this, `HttpResponse` provides a helper function:
+
+```typescript title=Definition
+function rebuild(statusCode?: number, contentType?: string): void {}
+```
+
+This function rebuilds the entire HTTP response using the OpenAPI response
+definition for the given status code and content type.
+
+### What rebuild does
+
+Calling rebuild will:
+- Select the matching response definition from the OpenAPI specification 
+- Set response.statusCode to the provided value 
+- Generate valid response data based on the response schema 
+- Generate valid response headers defined in the specification 
+- Replace previously generated response data and headers
+
+This ensures the response remains valid after changing the status code.
+
+### When to Use rebuild
+
+Use rebuild when:
+- You change the response status code 
+- You want to switch to a different response definition 
+- You want Mokapi to regenerate valid example data and headers
+
+You do not need to call rebuild if you only modify fields within the
+already generated response.data.
+
+### Example: Changing the Status Code Safely
 
 ```javascript
 import { on } from 'mokapi'
 
 export default function() {
     on('http', (request, response) => {
-        response.statusCode = 200
-        response.headers = {
-            'Content-Type': 'application/json'
-        }
-        response.data = {
-            message: 'Hello World'
+        if (request.path.petId === 10) {
+            // Switch to a different OpenAPI response
+            response.rebuild(404, 'application/json')
+
+            // Modify only what matters
+            response.data.message = 'Pet not found'
         }
     })
 }
 ```
 
-## Body vs Data
+### Parameter Defaults
 
-Use body to return a raw response body without OpenAPI encoding and validating.
+- If `statusCode` is not provided, Mokapi selects the OpenAPI `default` response.
+- If `contentType` is not provided, Mokapi selects the first content type
+  defined for the selected status code in the OpenAPI specification.
 
-Use data to return structured data that should be validated and encoded
-according to the OpenAPI response definition
+### Error handling
 
-If both body and data are set, body takes precedence
+If `response.rebuild()` throws an error, and it is not caught, the current event
+handler is skipped and no response modifications from that handler are applied.

engine/common/http.go

@@ -11,6 +11,8 @@ type HttpEventResponse struct {
 	StatusCode int            `json:"statusCode"`
 	Body       string         `json:"body"`
 	Data       any            `json:"data"`
+
+	Rebuild func(statusCode int, contentType string) `json:"-"`
 }
 
 type HttpEventRequest struct {

js/mokapi/on.go

@@ -122,7 +122,7 @@ func getHashes(args ...any) ([][]byte, error) {
 	for _, arg := range args {
 		b, err := json.Marshal(arg)
 		if err != nil {
-			return nil, fmt.Errorf("unable to marshal arg")
+			return nil, fmt.Errorf("failed to marshal arg: %v", err)
 		}
 		result = append(result, b)
 	}
@@ -151,6 +151,8 @@ func ArgToJs(arg any, vm *goja.Runtime) goja.Value {
 				switch key {
 				case "headers":
 					p.KeyNormalizer = http.CanonicalHeaderKey
+				case "rebuild":
+					return rebuild(vm, v)
 				}
 
 				switch val.(type) {
@@ -165,3 +167,28 @@ func ArgToJs(arg any, vm *goja.Runtime) goja.Value {
 		return vm.ToValue(v)
 	}
 }
+
+func rebuild(vm *goja.Runtime, res *common.HttpEventResponse) goja.Value {
+	if res.Rebuild == nil {
+		return vm.ToValue(func() {})
+	}
+	return vm.ToValue(func(statusCode goja.Value, contentType goja.Value) {
+		s := int64(0)
+		c := ""
+		if statusCode != nil {
+			if statusCode.ExportType().Kind() != reflect.Int64 {
+				panic(fmt.Sprintf("response.rebuild failed: statusCode must be a number: got %v", util.JsType(statusCode.Export())))
+			} else {
+				s = statusCode.ToInteger()
+			}
+		}
+		if contentType != nil {
+			if contentType.ExportType().Kind() != reflect.String {
+				panic(fmt.Sprintf("response.rebuild failed: contentType must be a string: got %v", util.JsType(contentType.Export())))
+			} else {
+				c = contentType.String()
+			}
+		}
+		res.Rebuild(int(s), c)
+	})
+}

js/mokapi/on_test.go

@@ -490,6 +490,118 @@ m.on('http', (req, res) => {
 				r.Equal(t, map[string]any{"foo": "yuh"}, res.Data)
 			},
 		},
+		{
+			name: "rebuild function not defined",
+			script: `
+const m = require('mokapi')
+m.on('http', (req, res) => {
+	res.rebuild();
+})
+`,
+			run: func(evt common.EventEmitter) []*common.Action {
+				res := &common.HttpEventResponse{Data: map[string]any{"foo": "bar"}}
+				return evt.Emit("http", &common.HttpEventRequest{}, res)
+			},
+			test: func(t *testing.T, actions []*common.Action, err error) {
+				r.NoError(t, err)
+
+				r.Nil(t, actions[0].Error)
+
+				var res *common.HttpEventResponse
+				err = json.Unmarshal([]byte(actions[0].Parameters[1].(string)), &res)
+				r.Equal(t, map[string]any{"foo": "bar"}, res.Data)
+			},
+		},
+		{
+			name: "rebuild function updates data",
+			script: `
+const m = require('mokapi')
+m.on('http', (req, res) => {
+	res.rebuild();
+})
+`,
+			run: func(evt common.EventEmitter) []*common.Action {
+				res := &common.HttpEventResponse{Data: map[string]any{"foo": "bar"}}
+				res.Rebuild = func(statusCode int, contentType string) {
+					res.Data = map[string]any{"foo": "yuh"}
+				}
+				return evt.Emit("http", &common.HttpEventRequest{}, res)
+			},
+			test: func(t *testing.T, actions []*common.Action, err error) {
+				r.NoError(t, err)
+
+				r.Nil(t, actions[0].Error)
+
+				var res *common.HttpEventResponse
+				err = json.Unmarshal([]byte(actions[0].Parameters[1].(string)), &res)
+				r.Equal(t, map[string]any{"foo": "yuh"}, res.Data)
+			},
+		},
+		{
+			name: "rebuild function with parameters",
+			script: `
+const m = require('mokapi')
+m.on('http', (req, res) => {
+	res.rebuild(200, 'application/json');
+})
+`,
+			run: func(evt common.EventEmitter) []*common.Action {
+				res := &common.HttpEventResponse{Data: map[string]any{"foo": "bar"}}
+				res.Rebuild = func(statusCode int, contentType string) {
+					res.Data = map[string]any{"statusCode": statusCode, "contentType": contentType}
+				}
+				return evt.Emit("http", &common.HttpEventRequest{}, res)
+			},
+			test: func(t *testing.T, actions []*common.Action, err error) {
+				r.NoError(t, err)
+
+				r.Nil(t, actions[0].Error)
+
+				var res *common.HttpEventResponse
+				err = json.Unmarshal([]byte(actions[0].Parameters[1].(string)), &res)
+				r.Equal(t, map[string]any{"statusCode": float64(200), "contentType": "application/json"}, res.Data)
+			},
+		},
+		{
+			name: "rebuild function wrong type statusCode",
+			script: `
+const m = require('mokapi')
+m.on('http', (req, res) => {
+	res.rebuild({ }, 'application/json');
+})
+`,
+			run: func(evt common.EventEmitter) []*common.Action {
+				res := &common.HttpEventResponse{Data: map[string]any{"foo": "bar"}}
+				res.Rebuild = func(statusCode int, contentType string) {}
+				return evt.Emit("http", &common.HttpEventRequest{}, res)
+			},
+			test: func(t *testing.T, actions []*common.Action, err error) {
+				r.NoError(t, err)
+
+				r.NotNil(t, actions[0].Error)
+				r.Equal(t, "response.rebuild failed: statusCode must be a number: got Object", actions[0].Error.Message)
+			},
+		},
+		{
+			name: "rebuild function wrong type contentType",
+			script: `
+const m = require('mokapi')
+m.on('http', (req, res) => {
+	res.rebuild(100, 200);
+})
+`,
+			run: func(evt common.EventEmitter) []*common.Action {
+				res := &common.HttpEventResponse{Data: map[string]any{"foo": "bar"}}
+				res.Rebuild = func(statusCode int, contentType string) {}
+				return evt.Emit("http", &common.HttpEventRequest{}, res)
+			},
+			test: func(t *testing.T, actions []*common.Action, err error) {
+				r.NoError(t, err)
+
+				r.NotNil(t, actions[0].Error)
+				r.Equal(t, "response.rebuild failed: contentType must be a string: got Integer", actions[0].Error.Message)
+			},
+		},
 	}
 
 	for _, tc := range testcases {

js/mokapi/proxy.go

@@ -54,8 +54,10 @@ func (p *Proxy) Get(key string) goja.Value {
 		v := target.MapIndex(reflect.ValueOf(key))
 		return p.toJSValue(key, v)
 	case reflect.Struct:
-		f := getFieldByTag(target, key, "json")
-		return p.toJSValue(key, f)
+		f := getField(target, key, "json")
+		if f.IsValid() {
+			return p.toJSValue(key, f)
+		}
 	case reflect.Slice:
 		switch key {
 		case "length":
@@ -116,9 +118,8 @@ func (p *Proxy) Get(key string) goja.Value {
 			}
 			return goja.Undefined()
 		}
-	default:
-		return goja.Undefined()
 	}
+	panic(fmt.Sprintf("%s is not defined", key))
 }
 
 func (p *Proxy) Has(key string) bool {
@@ -133,7 +134,7 @@ func (p *Proxy) Has(key string) bool {
 		k := target.MapIndex(reflect.ValueOf(key))
 		return k.IsValid()
 	case reflect.Struct:
-		f := getFieldByTag(target, key, "json")
+		f := getField(target, key, "json")
 		return f.IsValid()
 	default:
 		return false
@@ -155,7 +156,7 @@ func (p *Proxy) Set(key string, value goja.Value) bool {
 		target.SetMapIndex(reflect.ValueOf(key), v)
 		return true
 	case reflect.Struct:
-		f := getFieldByTag(target, key, "json")
+		f := getField(target, key, "json")
 		err := assignValue(f, value.Export(), key)
 		if err != nil {
 			panic(p.vm.ToValue(err))
@@ -216,6 +217,10 @@ func (p *Proxy) normalizeKey(key string) string {
 }
 
 func (p *Proxy) toJSValue(key string, v reflect.Value) goja.Value {
+	if !v.IsValid() {
+		return goja.Undefined()
+	}
+
 	if p.ToJSValue != nil {
 		return p.ToJSValue(p.vm, key, v.Interface())
 	}
@@ -242,10 +247,15 @@ func (p *Proxy) Export() any {
 	return Export(v)
 }
 
-func getFieldByTag(structValue reflect.Value, name, tag string) reflect.Value {
+func getField(structValue reflect.Value, name, tag string) reflect.Value {
+	name = capitalize(name)
 	for i := 0; i < structValue.NumField(); i++ {
-		v := structValue.Type().Field(i).Tag.Get(tag)
-		tagValues := strings.Split(v, ",")
+		f := structValue.Type().Field(i)
+		if f.Name == name {
+			return structValue.Field(i)
+		}
+		t := f.Tag.Get(tag)
+		tagValues := strings.Split(t, ",")
 		for _, tagValue := range tagValues {
 			if tagValue == name {
 				return structValue.Field(i)
@@ -362,3 +372,7 @@ func unwrap(v reflect.Value) reflect.Value {
 		}
 	}
 }
+
+func capitalize(s string) string {
+	return strings.ToUpper(s[0:1]) + s[1:]
+}