From fe48a099fa3817022d0a82cf181b999b08d71d24 Mon Sep 17 00:00:00 2001 From: Nitish Raj Moganti Date: Sun, 15 Dec 2024 13:49:47 +0530 Subject: [PATCH 1/3] Documentation for Custom http status code --- .../guide/httpServer/customHttpStatusCode | 58 +++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 src/main/docs/guide/httpServer/customHttpStatusCode diff --git a/src/main/docs/guide/httpServer/customHttpStatusCode b/src/main/docs/guide/httpServer/customHttpStatusCode new file mode 100644 index 0000000000..f6b6337ffa --- /dev/null +++ b/src/main/docs/guide/httpServer/customHttpStatusCode @@ -0,0 +1,58 @@ +The Micronaut framework supports Custom HTTP Status Codes . This feature enables developers to define and use HTTP status codes beyond the standard ones, allowing integration with systems or APIs that rely on non-standard status codes. + + +=== Custom HTTP Status Codes +Micronaut now supports arbitrary HTTP status codes that are not part of the predefined `HttpStatus` enum. Developers can specify any valid HTTP status code within the range `100-599`. + +==== Usage +- `HttpResponse.status(int statusCode)`: +Allows setting a custom HTTP status code. +- `HttpResponse.status(int statusCode, String reason)`: +Allows setting a custom HTTP status code along with a reason phrase. + +==== Examples +[source,java] +---- +HttpResponse.status(450, "Blocked by ISP"); +HttpResponse.status(599, "Network Connect Timeout Error"); +---- + +=== Validation of Status Codes +Micronaut ensures that the custom status codes are within the valid HTTP range (`100-599`). + +- Valid Codes: Between `100` and `599`. +- Invalid Codes: Codes outside this range (e.g., `700` or negative values) will throw an `IllegalArgumentException`. + +==== Examples +[source,java] +---- +HttpResponse.status(700); // Throws IllegalArgumentException +HttpResponse.status(-1); // Throws IllegalArgumentException +---- + +=== Client Response Handling +The HTTP client in Micronaut can now process custom status codes returned by servers. Custom codes are treated appropriately based on their range: +- Codes `<400` are treated as successful responses. +- Codes `>=400` trigger exceptions. + +==== Example +[source,java] +---- +try { + HttpResponse response = httpClient.toBlocking().exchange("/example"); + int statusCode = response.code(); +} catch (HttpClientResponseException e) { + if (e.getStatus().getCode() == 450) { + // Handle custom status code + } +} +---- + +== Backward Compatibility +This feature is fully backward-compatible: +- Existing applications using predefined HTTP status codes remain unaffected. +- Custom status codes are additive, enabling new use cases without breaking existing behavior. + +== Summary +The addition of custom HTTP status code support in Micronaut enhances its flexibility, enabling developers to integrate with systems using non-standard codes. With this feature, arbitrary HTTP status codes can be used while maintaining full compatibility with existing functionality. + From 249186d2feb94e8083272003cf34b0bd75982c8f Mon Sep 17 00:00:00 2001 From: Nitish Raj Moganti Date: Thu, 26 Dec 2024 14:22:54 +0000 Subject: [PATCH 2/3] Resolved comments and added snippets --- .../guide/httpServer/customHttpStatusCode | 40 +++++-------------- src/main/docs/guide/toc.yml | 1 + 2 files changed, 11 insertions(+), 30 deletions(-) diff --git a/src/main/docs/guide/httpServer/customHttpStatusCode b/src/main/docs/guide/httpServer/customHttpStatusCode index f6b6337ffa..aa781b0122 100644 --- a/src/main/docs/guide/httpServer/customHttpStatusCode +++ b/src/main/docs/guide/httpServer/customHttpStatusCode @@ -1,8 +1,6 @@ -The Micronaut framework supports Custom HTTP Status Codes . This feature enables developers to define and use HTTP status codes beyond the standard ones, allowing integration with systems or APIs that rely on non-standard status codes. - - +The Micronaut framework supports custom HTTP status codes .This feature enables developers to define and use HTTP status codes beyond the standard ones, allowing integration with systems or APIs that rely on non-standard status codes. === Custom HTTP Status Codes -Micronaut now supports arbitrary HTTP status codes that are not part of the predefined `HttpStatus` enum. Developers can specify any valid HTTP status code within the range `100-599`. +Micronaut supports arbitrary HTTP status codes that are not part of the predefined `HttpStatus` enum. Developers can specify any valid HTTP status code within the range `100-599`. ==== Usage - `HttpResponse.status(int statusCode)`: @@ -10,28 +8,19 @@ Allows setting a custom HTTP status code. - `HttpResponse.status(int statusCode, String reason)`: Allows setting a custom HTTP status code along with a reason phrase. -==== Examples -[source,java] ----- -HttpResponse.status(450, "Blocked by ISP"); -HttpResponse.status(599, "Network Connect Timeout Error"); ----- +Below we can see how we support custom status codes and how to implement them. -=== Validation of Status Codes -Micronaut ensures that the custom status codes are within the valid HTTP range (`100-599`). +snippet::io.micronaut.http.HttpResponse[tags="getStatusMethod", indent=0, title="HttpResponse.java"] +Let's start with a simple example. Given the following class: -- Valid Codes: Between `100` and `599`. -- Invalid Codes: Codes outside this range (e.g., `700` or negative values) will throw an `IllegalArgumentException`. +snippet::io.micronaut.http.client.netty.FullNettyClientHttpResponse[tags="getBodyMethod", indent=0, title="FullNettyClientHttpResponse.java"] +Note how we use code() in the condition where we are checkimg custom http status code. -==== Examples -[source,java] ----- -HttpResponse.status(700); // Throws IllegalArgumentException -HttpResponse.status(-1); // Throws IllegalArgumentException ----- +snippet::io.micronaut.http.client.InvalidStatusSpec[tags="testInvalidStatus", indent=0, title="InvalidStatusSpec.groovy"] +This snippet includes a test for handling an invalid HTTP status code in a Micronaut application. === Client Response Handling -The HTTP client in Micronaut can now process custom status codes returned by servers. Custom codes are treated appropriately based on their range: +The HTTP client in Micronaut can process custom status codes returned by servers. Custom codes are treated appropriately based on their range: - Codes `<400` are treated as successful responses. - Codes `>=400` trigger exceptions. @@ -47,12 +36,3 @@ try { } } ---- - -== Backward Compatibility -This feature is fully backward-compatible: -- Existing applications using predefined HTTP status codes remain unaffected. -- Custom status codes are additive, enabling new use cases without breaking existing behavior. - -== Summary -The addition of custom HTTP status code support in Micronaut enhances its flexibility, enabling developers to integrate with systems using non-standard codes. With this feature, arbitrary HTTP status codes can be used while maintaining full compatibility with existing functionality. - diff --git a/src/main/docs/guide/toc.yml b/src/main/docs/guide/toc.yml index c40b29a1df..616f36ecac 100644 --- a/src/main/docs/guide/toc.yml +++ b/src/main/docs/guide/toc.yml @@ -109,6 +109,7 @@ httpServer: statusAnnotation: Response Status producesAnnotation: Response Content-Type consumesAnnotation: Accepted Request Content-Type + customHttpStatusCode: Supporting Custom Http Status Code reactiveServer: title: Reactive HTTP Request Processing bodyAnnotation: Using the @Body Annotation From 30c48a2f7f0654456c8764a50d40a259cb8e830a Mon Sep 17 00:00:00 2001 From: Nitish Raj Moganti Date: Tue, 31 Dec 2024 10:46:38 +0000 Subject: [PATCH 3/3] Modified customHttp adoc file based on comments --- src/main/docs/guide/httpServer/customHttpStatusCode | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/main/docs/guide/httpServer/customHttpStatusCode b/src/main/docs/guide/httpServer/customHttpStatusCode index aa781b0122..f2fe544fcd 100644 --- a/src/main/docs/guide/httpServer/customHttpStatusCode +++ b/src/main/docs/guide/httpServer/customHttpStatusCode @@ -1,4 +1,4 @@ -The Micronaut framework supports custom HTTP status codes .This feature enables developers to define and use HTTP status codes beyond the standard ones, allowing integration with systems or APIs that rely on non-standard status codes. +The Micronaut framework supports custom HTTP status codes. This feature enables developers to define and use HTTP status codes beyond the standard ones, allowing integration with systems or APIs that rely on non-standard status codes. === Custom HTTP Status Codes Micronaut supports arbitrary HTTP status codes that are not part of the predefined `HttpStatus` enum. Developers can specify any valid HTTP status code within the range `100-599`. @@ -31,7 +31,7 @@ try { HttpResponse response = httpClient.toBlocking().exchange("/example"); int statusCode = response.code(); } catch (HttpClientResponseException e) { - if (e.getStatus().getCode() == 450) { + if (e.code() == 450) { // Handle custom status code } }