feat(validation): align request/response validation and harden parsing/metrics behavior (#21)

## Summary

This PR completes the validation/options overhaul for JSON-RPC
request/response handling and aligns Spring auto-configuration with core
behavior.

Key updates:
- Added symmetric request/response validation options in `jsonrpc-core`
(ID rules, duplicate-member policies, field rejection policies).
- Added strict duplicate-member parsing support via shared payload
reader and wired it through core/webmvc/autoconfigure.
- Exposed and bound response parser/validator options in Spring Boot
auto-configuration.
- Fixed autoconfigure precedence so custom
`JsonRpcRequestValidationOptions` / `JsonRpcResponseValidationOptions`
beans are honored consistently.
- Added hard fail-fast constraints for invalid constructor/property
inputs (including positive-only metric method-tag cap).
- Enforced hard cap semantics for metric method-tag cardinality under
concurrency.
- Expanded tests across core/autoconfigure/webmvc/samples for
success/failure/branch/concurrency paths.
- Updated docs and metadata (configuration reference, migration mapping,
sample guides, expected JSON outputs).

## Related Issues

- Closes #20
- Related #

## Change Type

- [x] Bug fix
- [x] Feature
- [x] Refactor
- [x] Documentation
- [x] Test
- [x] Build/CI

## JSON-RPC Impact

Describe protocol-level impact, if any:

- [ ] No protocol behavior change
- [x] Request validation behavior changed
- [ ] Error mapping behavior changed
- [ ] Method registration/dispatch behavior changed

Details:
- Validation behavior is now more explicitly controlled through
symmetric request/response options.
- Duplicate-member rejection can be enforced consistently for
request/response raw parsing paths.
- Reserved method namespace (`rpc.*`) rejection and stricter fail-fast
constraints are enforced where configured.
- Default behavior remains RFC-oriented and documented; strict toggles
are opt-in via configuration.

## Validation

- [x] `./gradlew test`
- [x] `./gradlew check`
- [x] Added/updated tests for new behavior

## Documentation

- [x] Updated README (if needed)
- [x] Added migration notes for breaking changes (if any)

Author: limehee

README.md

@@ -183,11 +183,16 @@ Use `jsonrpc.validation.request.*` and `jsonrpc.validation.response.*` for fine-
 jsonrpc:
   validation:
     request:
+      require-id-member: false
+      allow-fractional-id: false
+      reject-response-fields: true
       params-type-violation-code-policy: INVALID_REQUEST
     response:
-      require-response-id-member: true
-      allow-fractional-response-id: false
-      allow-request-fields-in-response: false
+      require-id-member: true
+      allow-fractional-id: false
+      reject-request-fields: true
+      error-code:
+        policy: STANDARD_OR_SERVER_ERROR_RANGE
 ```
 
 For the full list of validation keys and defaults, see

docs/configuration-reference.md

@@ -12,18 +12,30 @@ All properties are under `jsonrpc.*` and are bound to `JsonRpcProperties`.
 | `jsonrpc.max-request-bytes`                                     | `int`                                 | `1048576`        | Raw HTTP request payload size limit in bytes                         |
 | `jsonrpc.scan-annotated-methods`                                | `boolean`                             | `true`           | Scan Spring beans for `@JsonRpcMethod`                               |
 | `jsonrpc.include-error-data`                                    | `boolean`                             | `false`          | Include `JsonRpcException.data` in error responses                   |
+| `jsonrpc.validation.request.require-json-rpc-version-20`        | `boolean`                             | `true`           | Require incoming request `jsonrpc` to equal `"2.0"`                  |
+| `jsonrpc.validation.request.require-id-member`                  | `boolean`                             | `false`          | Require incoming requests to include an `id` member                  |
+| `jsonrpc.validation.request.allow-null-id`                      | `boolean`                             | `true`           | Allow `id: null` in incoming requests                                |
+| `jsonrpc.validation.request.allow-string-id`                    | `boolean`                             | `true`           | Allow string IDs in incoming requests                                |
+| `jsonrpc.validation.request.allow-numeric-id`                   | `boolean`                             | `true`           | Allow numeric IDs in incoming requests                               |
+| `jsonrpc.validation.request.allow-fractional-id`                | `boolean`                             | `true`           | Allow fractional numeric IDs in incoming requests                    |
+| `jsonrpc.validation.request.reject-response-fields`             | `boolean`                             | `false`          | Reject request objects containing `result`/`error`                   |
+| `jsonrpc.validation.request.reject-duplicate-members`           | `boolean`                             | `false`          | Reject duplicate members while parsing raw request JSON              |
 | `jsonrpc.validation.request.params-type-violation-code-policy`  | `INVALID_PARAMS` or `INVALID_REQUEST` | `INVALID_PARAMS` | Error code used when `params` exists but is neither object nor array |
 | `jsonrpc.validation.response.require-json-rpc-version-20`       | `boolean`                             | `true`           | Require incoming response `jsonrpc` to equal `"2.0"`                 |
-| `jsonrpc.validation.response.require-response-id-member`        | `boolean`                             | `true`           | Require incoming responses to include an `id` member                 |
-| `jsonrpc.validation.response.allow-null-response-id`            | `boolean`                             | `true`           | Allow `id: null` in incoming responses                               |
-| `jsonrpc.validation.response.allow-string-response-id`          | `boolean`                             | `true`           | Allow string IDs in incoming responses                               |
-| `jsonrpc.validation.response.allow-numeric-response-id`         | `boolean`                             | `true`           | Allow numeric IDs in incoming responses                              |
-| `jsonrpc.validation.response.allow-fractional-response-id`      | `boolean`                             | `true`           | Allow fractional numeric IDs in incoming responses                   |
+| `jsonrpc.validation.response.require-id-member`                 | `boolean`                             | `true`           | Require incoming responses to include an `id` member                 |
+| `jsonrpc.validation.response.allow-null-id`                     | `boolean`                             | `true`           | Allow `id: null` in incoming responses                               |
+| `jsonrpc.validation.response.allow-string-id`                   | `boolean`                             | `true`           | Allow string IDs in incoming responses                               |
+| `jsonrpc.validation.response.allow-numeric-id`                  | `boolean`                             | `true`           | Allow numeric IDs in incoming responses                              |
+| `jsonrpc.validation.response.allow-fractional-id`               | `boolean`                             | `true`           | Allow fractional numeric IDs in incoming responses                   |
 | `jsonrpc.validation.response.require-exclusive-result-or-error` | `boolean`                             | `true`           | Require exactly one of `result` or `error`                           |
 | `jsonrpc.validation.response.require-error-object-when-present` | `boolean`                             | `true`           | Require `error` to be an object when present                         |
 | `jsonrpc.validation.response.require-integer-error-code`        | `boolean`                             | `true`           | Require `error.code` to be an integer                                |
 | `jsonrpc.validation.response.require-string-error-message`      | `boolean`                             | `true`           | Require `error.message` to be a string                               |
-| `jsonrpc.validation.response.allow-request-fields-in-response`  | `boolean`                             | `true`           | Allow request-only fields (`method`/`params`) on responses           |
+| `jsonrpc.validation.response.reject-request-fields`             | `boolean`                             | `false`          | Reject response objects containing `method`/`params`                 |
+| `jsonrpc.validation.response.reject-duplicate-members`          | `boolean`                             | `false`          | Reject duplicate members while parsing raw response JSON             |
+| `jsonrpc.validation.response.error-code.policy`                 | `JsonRpcResponseErrorCodePolicy`      | `ANY_INTEGER`    | Accepted integer range policy for response `error.code`              |
+| `jsonrpc.validation.response.error-code.range.min`              | `Integer`                             | `null`           | Inclusive minimum for `CUSTOM_RANGE`                                 |
+| `jsonrpc.validation.response.error-code.range.max`              | `Integer`                             | `null`           | Inclusive maximum for `CUSTOM_RANGE`                                 |
 | `jsonrpc.method-registration-conflict-policy`                   | `REJECT` or `REPLACE`                 | `REJECT`         | Duplicate method name registration policy                            |
 | `jsonrpc.method-allowlist`                                      | `List<String>`                        | `[]`             | Allowlist for method access filtering                                |
 | `jsonrpc.method-denylist`                                       | `List<String>`                        | `[]`             | Denylist for method access filtering (higher priority)               |
@@ -34,6 +46,12 @@ All properties are under `jsonrpc.*` and are bound to `JsonRpcProperties`.
 | `jsonrpc.notification-executor-enabled`                         | `boolean`                             | `false`          | Enable executor-backed notification dispatch                         |
 | `jsonrpc.notification-executor-bean-name`                       | `String`                              | `""`             | Preferred executor bean name for notifications                       |
 
+`JsonRpcResponseErrorCodePolicy` values:
+- `ANY_INTEGER`
+- `STANDARD_ONLY`
+- `STANDARD_OR_SERVER_ERROR_RANGE`
+- `CUSTOM_RANGE`
+
 ## 2. Validation Rules (Fail Fast)
 
 Startup fails with `IllegalArgumentException` when any of these conditions occur:
@@ -52,12 +70,18 @@ Startup fails with `IllegalArgumentException` when any of these conditions occur
 - `jsonrpc.validation.request` is null
 - `jsonrpc.validation.request.params-type-violation-code-policy` is null
 - `jsonrpc.validation.response` is null
+- `jsonrpc.validation.response.error-code` is null
+- `jsonrpc.validation.response.error-code.policy` is null
+- `jsonrpc.validation.response.error-code.range` is null
+- `jsonrpc.validation.response.require-integer-error-code=false` with `jsonrpc.validation.response.error-code.policy != ANY_INTEGER`
+- `jsonrpc.validation.response.error-code.policy=CUSTOM_RANGE` and either range bound is missing
+- `jsonrpc.validation.response.error-code.policy=CUSTOM_RANGE` and `range.min > range.max`
 - allowlist/denylist list itself is null
 - allowlist/denylist contains null or blank values
 
 ## 3. Runtime Behavior Priority
 
-## 3.1 Method access filtering
+### 3.1 Method access filtering
 
 Priority:
 
@@ -69,9 +93,10 @@ Rules:
 
 - denylist always overrides allowlist
 - if allowlist is non-empty, methods not in allowlist are denied
-- `rpc.*` methods are blocked by registry independently of allow/deny lists
+- `rpc.*` methods are blocked by request validation, and also by the default registry independently of allow/deny
+  lists
 
-## 3.2 Notification executor resolution
+### 3.2 Notification executor resolution
 
 When `jsonrpc.notification-executor-enabled=true`, resolution order is:
 
@@ -82,7 +107,7 @@ When `jsonrpc.notification-executor-enabled=true`, resolution order is:
 
 If a configured bean name is missing, startup fails.
 
-## 3.3 Method registration conflict handling
+### 3.3 Method registration conflict handling
 
 - `REJECT`: first duplicate fails registration.
 - `REPLACE`: later registration wins.
@@ -108,7 +133,7 @@ Example environment variable mapping:
 
 ## 5. Example Configurations
 
-## 5.1 Baseline production profile
+### 5.1 Baseline production profile
 
 ```yaml
 jsonrpc:
@@ -120,40 +145,57 @@ jsonrpc:
   include-error-data: false
   validation:
     request:
+      require-json-rpc-version-20: true
+      require-id-member: false
+      allow-null-id: true
+      allow-string-id: true
+      allow-numeric-id: true
+      allow-fractional-id: true
+      reject-response-fields: false
+      reject-duplicate-members: false
       params-type-violation-code-policy: INVALID_PARAMS
     response:
       require-json-rpc-version-20: true
-      require-response-id-member: true
-      allow-null-response-id: true
-      allow-string-response-id: true
-      allow-numeric-response-id: true
-      allow-fractional-response-id: true
+      require-id-member: true
+      allow-null-id: true
+      allow-string-id: true
+      allow-numeric-id: true
+      allow-fractional-id: true
       require-exclusive-result-or-error: true
       require-error-object-when-present: true
       require-integer-error-code: true
       require-string-error-message: true
-      allow-request-fields-in-response: true
+      reject-request-fields: false
+      reject-duplicate-members: false
+      error-code:
+        policy: ANY_INTEGER
+        range:
+          min: null
+          max: null
   method-allowlist: [ ]
   method-denylist: [ ]
 ```
 
-## 5.2 Strict access profile
+### 5.2 Strict response error-code profile
 
 ```yaml
 jsonrpc:
-  method-allowlist: [ user.find, user.update ]
-  method-denylist: [ user.delete ]
+  validation:
+    response:
+      reject-request-fields: true
+      error-code:
+        policy: STANDARD_OR_SERVER_ERROR_RANGE
 ```
 
-## 5.3 Async notification profile
+### 5.3 Async notification profile
 
 ```yaml
 jsonrpc:
   notification-executor-enabled: true
   notification-executor-bean-name: applicationTaskExecutor
 ```
 
-## 5.4 Metrics-rich profile
+### 5.4 Metrics-rich profile
 
 ```yaml
 jsonrpc:
@@ -163,7 +205,26 @@ jsonrpc:
   metrics-max-method-tag-values: 200
 ```
 
-## 6. IDE Auto-completion and Metadata
+## 6. Migration Notes (Response Validation Key Rename)
+
+The old keys below are migration references only.
+They are not bound by current auto-configuration and should not be used in new setups.
+Use the canonical symmetric keys in the right column.
+
+| Old key                                                        | New key                                             |
+|----------------------------------------------------------------|-----------------------------------------------------|
+| `jsonrpc.validation.response.require-response-id-member`       | `jsonrpc.validation.response.require-id-member`     |
+| `jsonrpc.validation.response.allow-null-response-id`           | `jsonrpc.validation.response.allow-null-id`         |
+| `jsonrpc.validation.response.allow-string-response-id`         | `jsonrpc.validation.response.allow-string-id`       |
+| `jsonrpc.validation.response.allow-numeric-response-id`        | `jsonrpc.validation.response.allow-numeric-id`      |
+| `jsonrpc.validation.response.allow-fractional-response-id`     | `jsonrpc.validation.response.allow-fractional-id`   |
+| `jsonrpc.validation.response.allow-request-fields-in-response` | `jsonrpc.validation.response.reject-request-fields` |
+
+Inversion rule:
+
+- `reject-request-fields = !allow-request-fields-in-response`
+
+## 7. IDE Auto-completion and Metadata
 
 The project ships Spring Boot configuration metadata via:
 
@@ -173,10 +234,14 @@ The project ships Spring Boot configuration metadata via:
 This enables:
 
 - property key completion
-- enum value suggestions (`REJECT`, `REPLACE`, `INVALID_PARAMS`, `INVALID_REQUEST`)
+- enum value suggestions (`REJECT`, `REPLACE`, `INVALID_PARAMS`, `INVALID_REQUEST`, error-code policy values)
+- example numeric suggestions for `jsonrpc.validation.response.error-code.range.min/max`
 - metadata hints in IntelliJ and Spring-aware tooling
 
-## 7. Related References
+Hints are suggestions for IDE completion only. They do not restrict allowed runtime values unless validation rules
+explicitly enforce constraints.
+
+## 8. Related References
 
 - Spring setup details: [`spring-boot-guide.md`](spring-boot-guide.md)
 - Binding and registration details: [`registration-and-binding.md`](registration-and-binding.md)

docs/index.md

@@ -27,7 +27,12 @@
 - Failure diagnosis and fixes: [`troubleshooting.md`](troubleshooting.md)
 - Release and publish flow: [`release-checklist.md`](release-checklist.md)
 
-## 5. Repository-Level Docs
+## 5. Samples
+
+- Spring Boot sample: [`../samples/spring-boot-demo/README.md`](../samples/spring-boot-demo/README.md)
+- Pure Java sample: [`../samples/pure-java-demo/README.md`](../samples/pure-java-demo/README.md)
+
+## 6. Repository-Level Docs
 
 - Project overview: [`../README.md`](../README.md)
 - Contribution workflow: [`../CONTRIBUTING.md`](../CONTRIBUTING.md)

docs/protocol-and-compliance.md

@@ -55,6 +55,9 @@ Implementation constants are in `JsonRpcErrorCode` and messages in `JsonRpcConst
 - `JsonRpcResponseValidator`
 - `JsonRpcResponseValidationOptions`
 
+`DefaultJsonRpcResponseParser` can parse from `JsonNode`, `String`, or `byte[]`, and can optionally reject duplicate
+members during raw JSON parsing.
+
 These APIs are transport-agnostic and useful for bidirectional channels (for example WebSocket) where
 request/response envelopes may arrive on the same connection.
 
@@ -79,18 +82,21 @@ This library does not expose predefined strict/lenient modes; policy is controll
 `JsonRpcResponseValidationOptions` exposes per-rule switches:
 
 - `requireJsonRpcVersion20` (default: `true`)
-- `requireResponseIdMember` (default: `true`)
-- `allowNullResponseId` (default: `true`)
-- `allowStringResponseId` (default: `true`)
-- `allowNumericResponseId` (default: `true`)
-- `allowFractionalResponseId` (default: `true`)
+- `requireIdMember` (default: `true`)
+- `allowNullId` (default: `true`)
+- `allowStringId` (default: `true`)
+- `allowNumericId` (default: `true`)
+- `allowFractionalId` (default: `true`)
 - `requireExclusiveResultOrError` (default: `true`)
 - `requireErrorObjectWhenPresent` (default: `true`)
 - `requireIntegerErrorCode` (default: `true`)
 - `requireStringErrorMessage` (default: `true`)
-- `allowRequestFieldsInResponse` (default: `true`)
+- `rejectRequestFields` (default: `false`)
+- `rejectDuplicateMembers` (default: `false`)
+- `errorCodePolicy` (default: `ANY_INTEGER`)
+- `errorCodeRangeMin` / `errorCodeRangeMax` (default: `null`, used with `CUSTOM_RANGE`)
 
-`allowRequestFieldsInResponse=true` is a compatibility default and is not an RFC MUST rule.
+`rejectRequestFields=false` is a compatibility default and is not an RFC MUST rule.
 
 ## `id` Handling Details
 
@@ -108,8 +114,9 @@ This library does not expose predefined strict/lenient modes; policy is controll
 
 ## Reserved Method Namespace
 
-Methods starting with `rpc.` are rejected at registration (`IllegalArgumentException`) to preserve reserved namespace
-semantics.
+Methods starting with `rpc.` are treated as invalid requests during request validation (`-32600`).
+Default in-memory registration also rejects `rpc.*` method names (`IllegalArgumentException`), so both registration and
+dispatch paths preserve reserved namespace semantics.
 
 ## HTTP Mapping Notes
 

docs/pure-java-guide.md

@@ -207,6 +207,7 @@ JsonRpcDispatcher dispatcher = new JsonRpcDispatcher(
 ```
 
 This keeps protocol behavior while letting you customize policy and implementation.
+`maxBatchSize` must be greater than `0` (fail-fast `IllegalArgumentException` otherwise).
 
 `JsonRpcParamsTypeViolationCodePolicy` controls which code is used when request `params` is present but not
 an object/array: