https://github.com/michaeltelford/rack_jsonparser
Rack middleware for processing JSON requests and responses
https://github.com/michaeltelford/rack_jsonparser
json rack rack-application rack-jsonparser rack-middleware ruby
Last synced: 28 days ago
JSON representation
Rack middleware for processing JSON requests and responses
- Host: GitHub
- URL: https://github.com/michaeltelford/rack_jsonparser
- Owner: michaeltelford
- License: mit
- Created: 2017-09-09T21:31:27.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2019-06-17T03:31:43.000Z (about 7 years ago)
- Last Synced: 2025-03-06T01:18:36.107Z (over 1 year ago)
- Topics: json, rack, rack-application, rack-jsonparser, rack-middleware, ruby
- Language: Ruby
- Homepage: https://rubygems.org/gems/rack-jsonparser
- Size: 13.7 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Rack::JSONParser Middleware
Rack middleware which transforms an incoming request's JSON string into a `Hash` and any outgoing ruby `Object` back into a JSON string to be returned to the client.
- The client sends/receives only JSON strings
- The `app` (rack application) using the middleware sends/receives only ruby objects (no JSON parsing)
- The `Rack::JSONParser` middleware handles the parsing of the request/response to/from JSON/Object so you don't have to
The difference between this and other middleware doing the same job is that it's fast! This middleware uses the '[oj](https://github.com/ohler55/oj)' gem which gives faster processing than the `json` gem. This middleware is also configurable enabling predictive and controlled parsing. It stays out of your way when you don't need it and is seamless when you do.
## Installation
Add this line to your application's `Gemfile`:
```ruby
gem 'rack-jsonparser'
```
And then execute:
$ bundle
Or install it yourself with:
$ gem install rack-jsonparser
Then `require` it in your rack application with:
```ruby
require 'rack/json_parser'
```
## Usage
### Request
The incoming requests JSON body will be available in `env['request.payload']`.
### Response
As per the rack interface your app should return an array containing the status, headers, body. This doesn't change; just remember to include the header `Content-Type: application/json`. The response body can be:
- `String`: Treated as an already valid JSON string and is not processed by the middleware
- `Hash`: The recommended type of ruby object to return, will be processed into a JSON string and sent back to the client
- `Object`: Any ruby object can be returned, the resulting JSON will depend on the `Object#to_s` output
**Note** that the above objects should **not** be encased in an `Array` just to comply with the Rack interface. The middleware will automatically encase the generated JSON `String` into an `Array` so it complies with Rack.
### Example
Below is a sample `rack` app which uses the middleware to send and receive JSON:
> config.ru
```ruby
require 'rack/json_parser'
# Notice how the `request.payload` is a Hash, not a JSON string
# We return a Hash instance (or any Ruby object) for the response body,
# no need to encase in an array, the middleware will do this.
# We can turn off the request/response parsing via the `use` method (defaults to true)
# Parsing will only occur if enabled AND the `Content-Type` is `application/json`
handler = proc do |env|
payload = env['request.payload']
full_name = payload['forenames'].push(payload['surname']).join(' ')
res_hash = { 'full_name' => full_name }
[200, { 'Content-Type' => 'application/json' }, res_hash]
end
app = Rack::Builder.new do
use Rack::JSONParser, transform_request: true, transform_response: true
map('/hello') { run handler }
end
run app
```
Run the above `config.ru` rack app with:
$ rackup
Then query the app with:
```shell
curl -X POST \
http://localhost:9292/hello \
-H 'content-type: application/json' \
-d '{
"forenames": [
"Napolean",
"Neech"
],
"surname":"Manly"
}'
```
And the JSON response will be:
```json
{
"full_name":"Napolean Neech Manly"
}
```
## Configuration
The middleware is configurable so request/response processing can be turned off via the `use` method parameters if desired, see usage above.
In addition, the middleware only transforms the request/response if the `Content-Type` header is correctly set to `application/json`. This applies to both the request sent from the client and the response sent from the `app`; allowing for several types of response content to be served by the application without interference by the middleware. This however requires the client and rack `app` to set the `Content-Type` header correctly. If not, then the middleware will do nothing and simply pass through the request/response data which might lead to unexpected behavior.
If the middleware processes the response then it will also set/override the `Content-Length` header with the length of the JSON string being returned to the client.
## Ruby Version
This software was built with and supports:
- `~> 2.4.0`
## Contributing
Bug reports and pull requests are welcome on [GitHub](https://github.com/michaeltelford/rack_jsonparser).
## License
The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).