From 47f44d8fdb9ddf24f692f0100627f9a561c39a53 Mon Sep 17 00:00:00 2001 From: benhalstead Date: Fri, 30 Aug 2019 10:26:44 +0100 Subject: [PATCH] 2.0.2 release notes --- RELEASE_NOTES.md | 14 ++++- doc/ref/fac-json-ws.md | 131 ++++++++++++++++++++++++++++++++++++++++- 2 files changed, 143 insertions(+), 2 deletions(-) diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 953c631..9c35c95 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -5,6 +5,11 @@ to `grnc-bind`, code quality and documentation. This release is not backwards compatible, refer to the migration guide at the bottom of these notes for more information. + +## 2.0.x fixes + +See the section at the end of this document for fixes made since the initial 2.0.0 release + ## YAML Granitic now supports YAML for configuration and component definition files. This involves the @@ -319,4 +324,11 @@ packages. ## Default file locations Move your configuration files from `resource/config` to `config` and your component definition files from `resource/components` -to `comp-def` \ No newline at end of file +to `comp-def` + +# Post release fixes + +## 2.0.2 + + * [rdbms.Client missing InsertQIDParam method](https://github.com/graniticio/granitic/issues/35) + diff --git a/doc/ref/fac-json-ws.md b/doc/ref/fac-json-ws.md index f9bf1ab..23dc221 100644 --- a/doc/ref/fac-json-ws.md +++ b/doc/ref/fac-json-ws.md @@ -1 +1,130 @@ -#TODO +# JSON Web Services (JSONWs) + +Enabling the JSON web services facility automatically injects components into your [web service handlers](ws-handlers.md) +such that HTTP request bodies are parsed as JSON documents and HTTP response bodies are formatted as JSON documents. + +## Enabling + +The JSONWs facility is _disabled_ by default. To enable it, you must set the following in your configuration + +```json +{ + "Facilities": { + "JSONWs": true + } +} +``` + +### Prerequisites + +In order to use the JSONWs service, you must also enable the [HTTPServer facility](fac-http-server.md) + +## Configuration + +The default configuration for this facility can be found in the Granitic source under `facility/config/jsonws.json` +and is: + +```json +{ + "JSONWs":{ + "ResponseWriter": { + "DefaultHeaders": { + "Content-Type": "application/json; charset=utf-8" + } + }, + "Marshal": { + "PrettyPrint": false, + "IndentString": " ", + "PrefixString": "" + }, + "WrapMode": "BODY", + "ResponseWrapper": { + "ErrorsFieldName": "Errors", + "BodyFieldName": "Response" + } + } +} +``` + +### Headers + +`JSONWs.ResponseWriter.DefaultHeaders` contains HTTP response headers that will automatically added to every HTTP +response served by your application. The `Content-Type` header is by default set to `application/json; charset=utf-8` +which is the most common content type and encoding for JSON. + +You may add additional headers to the response by setting them in your configuration, e.g: + +```json +{ + "JSONWs":{ + "ResponseWriter": { + "DefaultHeaders": { + "My-Common-Header": "my value" + } + } + } +} +``` + +### JSON formatting + +The value of your [ws.Response.Body](https://godoc.org/github.com/graniticio/granitic/ws#Response) field will be marshalled +into JSON using Go's standard [json.Marshal](https://golang.org/pkg/encoding/json/#Marshal) function. + +If you set `JSONWs.Marshal.PrettyPrint` to `true`, [json.MarshalIndent](https://golang.org/pkg/encoding/json/#MarshalIndent) +will be used instead and the configuration values for `IndentString` and `PrefixString` will be passed into +that function. + +### Response wrapping + +By default, Granitic will use the JSON representation of your [ws.Response.Body](https://godoc.org/github.com/graniticio/granitic/ws#Response) +field as the entire HTTP response body. If an [error](ws-error.md) is found, the entire HTTP body is replaced with +the error document structure described below. + +Some applications prefer to have a consistent structure regardless of whether the request was successful or not. +That behaviour can be enabled in Granitic by setting `JSONWs.WrapMode` to `WRAP`. This means all requests will be +wrapped with: + +```json +{ + "Response": { }, + "Errors": {} +} +``` + +`Response` will only be populated if the request was successful and `Errors` will only be populated if a problem was +found. The labels `Response` and `Errors` can be modified by changing the `JSONWs.ResponseWrapper.ErrorsFieldName` and +`JSONWs.ResponseWrapper.BodyFieldName` configuration. + +## Behaviour + +Enabling this facility causes several components to be created and automatically injected into any [handlers](ws-handlers.md) +that you have defined that are of the type [handler.WsHandler](https://godoc.org/github.com/graniticio/granitic/ws/handler#WsHandler). + +### ResponseWriter + +Your handler's `ResponseWriter` field will be set to an instance of [ws.MarshallingResponseWriter](https://godoc.org/github.com/graniticio/granitic/ws#MarshallingResponseWriter). +This type is agnostic of the serialisation format, so it is customised for JSON serialisation using the +types defined in the [ws/json package](https://godoc.org/github.com/graniticio/granitic/ws/json). + +Together these types are responsible for populating the body, headers and status code of the HTTP responses +to your webservice request. + +The ResponseWriter is also injected into the [HTTP server](fac-http-server.md) so that it can handle requests +than are not matched to a handler (not found, too busy etc). + +### Unmarshaller + +Your handler's `ResponseWriter` field will be set to an instance of [json.Unmarshaller](https://godoc.org/github.com/graniticio/granitic/ws/json#Unmarshaller), +which is a simple wrapper over Go's built-in JSON decoding functions. + +## Customisation + +Granitic will not inject the above components into your handlers if the relevant target field is already populated. +So if you explicitly set an `Unmarshaller` or `ResponseWriter` with a reference to one of your own components in +your [component definition](ioc-definition-files.md) (or in a [component template](ioc-templates.md)) the `JSONWs` +facility will not overwrite it. + +### Advanced customisation + +If you want to use Granitic's `Unmarshaller`, but tweak it's behaviour you can make use of the \ No newline at end of file