• Stars
    star
    410
  • Rank 105,468 (Top 3 %)
  • Language
    Clojure
  • License
    Eclipse Public Li...
  • Created about 8 years ago
  • Updated about 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Clojure library for fast http api format negotiation, encoding and decoding.

Muuntaja Continuous Integration status cljdoc badge

Clojure library for fast HTTP format negotiation, encoding and decoding. Standalone library, but ships with adapters for ring (async) middleware & Pedestal-style interceptors. Explicit & extendable, supporting out-of-the-box JSON, EDN and Transit (both JSON & Msgpack). Ships with optional adapters for MessagePack and YAML.

Based on ring-middleware-format, but a complete rewrite (and up to 30x faster).

Rationale

  • explicit configuration
  • fast with good defaults
  • extendable & pluggable: new formats, behavior
  • typed exceptions - caught elsewhere
  • support runtime docs (like swagger) & inspection (negotiation results)
  • support runtime configuration (negotiation overrides)

Modules

  • metosin/muuntaja - the core abstractions + Jsonista JSON, EDN and Transit formats
  • metosin/muuntaja-cheshire - optional Cheshire JSON format
  • metosin/muuntaja-form - optional application/x-www-form-urlencoded formatter using ring-codec
  • metosin/muuntaja-msgpack - Messagepack format
  • metosin/muuntaja-yaml - YAML format

Posts

Check the docs on cljdoc.org for detailed API documentation as well as more guides on how to use Muuntaja.

Latest version

[metosin/muuntaja "0.6.8"]

Optionally, the parts can be required separately:

[metosin/muuntaja-form "0.6.8"]
[metosin/muuntaja-cheshire "0.6.8"]
[metosin/muuntaja-msgpack "0.6.8"]
[metosin/muuntaja-yaml "0.6.8"]

Muuntaja requires Java 1.8+

Quickstart

Standalone

Use default Muuntaja instance to encode & decode JSON:

(require '[muuntaja.core :as m])

(->> {:kikka 42}
     (m/encode "application/json"))
; => #object[java.io.ByteArrayInputStream]

(->> {:kikka 42}
     (m/encode "application/json")
     slurp)
; => "{\"kikka\":42}"

(->> {:kikka 42}
     (m/encode "application/json")
     (m/decode "application/json"))
; => {:kikka 42}

Ring

Automatic decoding of request body and response body encoding based on Content-Type, Accept and Accept-Charset headers:

(require '[muuntaja.middleware :as middleware])

(defn echo [request]
  {:status 200
   :body (:body-params request)})

; with defaults
(def app (middleware/wrap-format echo))

(def request
  {:headers
   {"content-type" "application/edn"
    "accept" "application/transit+json"}
   :body "{:kikka 42}"})
   
(app request)
; {:status 200,
;  :body #object[java.io.ByteArrayInputStream]
;  :headers {"Content-Type" "application/transit+json; charset=utf-8"}}

Automatic decoding of response body based on Content-Type header:

(-> request app m/decode-response-body)
; {:kikka 42}    

There is a more detailed Ring guide too. See also differences to ring-middleware-format & ring-json.

Interceptors

Muuntaja support Sieppari -style interceptors too. See muuntaja.interceptor for details.

Interceptors can be used with Pedestal too, all but the exception-interceptor which conforms to the simplified exception handling model of Sieppari.

Configuration

Explicit Muuntaja instance with custom EDN decoder options:

(def m
  (m/create
    (assoc-in
      m/default-options
      [:formats "application/edn" :decoder-opts]
      {:readers {'INC inc}})))

(->> "{:value #INC 41}"
     (m/decode m "application/edn"))
; => {:value 42}

Explicit Muuntaja instance with custom date formatter:

(def m
  (m/create
    (assoc-in
      m/default-options
      [:formats "application/json" :encoder-opts]
      {:date-format "yyyy-MM-dd"})))

(->> {:value (java.util.Date.)}
     (m/encode m "application/json")
     slurp)
; => "{\"value\":\"2019-10-15\"}"

Explicit Muuntaja instance with camelCase encode-key-fn:

(require '[camel-snake-kebab.core :as csk])

(def m
  (m/create
    (assoc-in
      m/default-options
      [:formats "application/json" :encoder-opts]
      {:encode-key-fn csk/->camelCase})))

(->> {:some-property "some-value"}
     (m/encode m "application/json")
     slurp)
; => "{\":someProperty\":\"some-value\"}"

Returning a function to encode transit-json:

(def encode-transit-json
  (m/encoder m "application/transit+json"))

(slurp (encode-transit-json {:kikka 42}))
; => "[\"^ \",\"~:kikka\",42]"

Encoding format

By default, encode writes value into a java.io.ByteArrayInputStream. This can be changed with a :return option, accepting the following values:

value description
:input-stream encodes into java.io.ByteArrayInputStream (default)
:bytes encodes into byte[]. Faster than Stream, enables NIO for servers supporting it
:output-stream encodes lazily into java.io.OutputStream via a callback function

All return types satisfy the following Protocols & Interfaces:

  • ring.protocols.StreamableResponseBody, Ring 1.6.0+ will stream these for you
  • clojure.io.IOFactory, so you can slurp the response

:input-stream

(def m (m/create (assoc m/default-options :return :input-stream)))

(->> {:kikka 42}
     (m/encode m "application/json"))
; #object[java.io.ByteArrayInputStream]

:bytes

(def m (m/create (assoc m/default-options :return :bytes)))

(->> {:kikka 42}
     (m/encode m "application/json"))
; #object["[B" 0x31f5d734 "[B@31f5d734"]

:output-stream

(def m (m/create (assoc m/default-options :return :output-stream)))

(->> {:kikka 42}
     (m/encode m "application/json"))
; <<StreamableResponse>>

Format-based return

(def m (m/create (assoc-in m/default-options [:formats "application/edn" :return] :output-stream)))

(->> {:kikka 42}
     (m/encode m "application/json"))
; #object[java.io.ByteArrayInputStream]

(->> {:kikka 42}
     (m/encode m "application/edn"))
; <<StreamableResponse>>

HTTP format negotiation

HTTP format negotiation is done using request headers for both request (content-type, including the charset) and response (accept and accept-charset). With the default options, a full match on the content-type is required, e.g. application/json. Adding a :matches regexp for formats enables more loose matching. See Configuration docs for more info.

Results of the negotiation are published into request & response under namespaced keys for introspection. These keys can also be set manually, overriding the content negotiation process.

Exceptions

When something bad happens, an typed exception is thrown. You should handle it elsewhere. Thrown exceptions have an ex-data with the following :type value (plus extra info to enable generating descriptive erros to clients):

  • :muuntaja/decode, input can't be decoded with the negotiated format & charset.
  • :muuntaja/request-charset-negotiation, request charset is illegal.
  • :muuntaja/response-charset-negotiation, could not negotiate a charset for the response.
  • :muuntaja/response-format-negotiation, could not negotiate a format for the response.

Server Spec

Request

  • :muuntaja/request, client-negotiated request format and charset as FormatAndCharset record. Will be used in the request pipeline.
  • :muuntaja/response, client-negotiated response format and charset as FormatAndCharset record. Will be used in the response pipeline.
  • :body-params contains the decoded body.

Response

  • :muuntaja/encode, if set to truthy value, the response body will be encoded regardles of the type (primitives!)
  • :muuntaja/content-type, handlers can use this to override the negotiated content-type for response encoding, e.g. setting it to application/edn will cause the response to be formatted in JSON.

Options

Default options

{:http {:extract-content-type extract-content-type-ring
        :extract-accept-charset extract-accept-charset-ring
        :extract-accept extract-accept-ring
        :decode-request-body? (constantly true)
        :encode-response-body? encode-collections}

 :allow-empty-input? true
 :return :input-stream

 :default-charset "utf-8"
 :charsets available-charsets

 :default-format "application/json"
 :formats {"application/json" json-format/json-format
           "application/edn" edn-format/edn-format
           "application/transit+json" transit-format/transit-json-format
           "application/transit+msgpack" transit-format/transit-msgpack-format}}

Profiling

YourKit supports open source projects with its full-featured Java Profiler. YourKit, LLC is the creator of YourKit Java Profiler and YourKit .NET Profiler, innovative and intelligent tools for profiling Java and .NET applications.

License

Picture

By Unknown. The drawing is signed "E. Ducretet", indicating that the apparatus was made by Eugene Ducretet, a prominent Paris scientific instrument manufacturer and radio researcher. The drawing was undoubtedly originally from the Ducretet instrument catalog. [Public domain], via Wikimedia Commons.

Original Code (ring-middleware-format)

Copyright © 2011, 2012, 2013, 2014 Nils Grunwald
Copyright © 2015, 2016 Juho Teperi

This library

Copyright © 2016-2020 Metosin Oy

Distributed under the Eclipse Public License 2.0.

More Repositories

1

malli

High-performance data-driven data specification library for Clojure/Script.
Clojure
1,499
star
2

reitit

A fast data-driven routing library for Clojure/Script
Clojure
1,313
star
3

spec-tools

Clojure(Script) tools for clojure.spec
Clojure
586
star
4

jsonista

Clojure library for fast JSON encoding and decoding.
Clojure
384
star
5

ring-swagger

Swagger Spec for Clojure Web Apps
Clojure
360
star
6

kekkonen

A remote (CQRS) API library for Clojure.
Clojure
220
star
7

tilakone

Minimalistic finite state machine (FSM) in Clojure
Clojure
192
star
8

sieppari

Small, fast, and complete interceptor library for Clojure/Script
Clojure
189
star
9

pohjavirta

Fast & Non-blocking Clojure wrapper for Undertow
Clojure
162
star
10

ring-http-response

Handling HTTP Statuses with Clojure(Script)
Clojure
139
star
11

schema-tools

Clojure(Script) tools for Plumatic Schema
Clojure
106
star
12

porsas

Experimental stuff for going fast with Clojure + JDBC & Async SQL
Clojure
95
star
13

talvi

Opinionated and Performant Web Application Stack for Clojure/Script
80
star
14

schema-viz

Plumatic Schema visualization using Graphviz.
Clojure
74
star
15

potpuri

Common clojure stuff.
Clojure
69
star
16

komponentit

Collection of bespoke Reagent components
Clojure
61
star
17

bat-test

Fast Clojure.test runner for Boot and Leiningen
Clojure
60
star
18

ring-swagger-ui

Swagger UI packaged for Ring Apps
Clojure
48
star
19

scjsv

Simple Clojure JSON-Schema Validator
Clojure
47
star
20

testit

Midje like assertions for Clojure.test
Clojure
43
star
21

compojure-api-examples

Compojure API example
Clojure
32
star
22

maailma

Opinionated environment variables library
Clojure
31
star
23

vega-tools

Utilities for working with Vega visualization grammar in ClojureScript.
Clojure
27
star
24

fnhouse-swagger

Swagger integration for fnhouse
Clojure
22
star
25

spec-swagger

Master Swagger2 & OpenAPI3 specs with Clojure(Script) & clojure.spec
Clojure
21
star
26

virhe

Beautiful Error Message for Clojure/Script
Clojure
20
star
27

reagent-dev-tools

Development tool panel for Reagent
Clojure
19
star
28

mallitaulut

Extract Malli schemas from SQL table schemas.
Clojure
17
star
29

eines

Simple Clojure and ClojureScript library for WebSocket communication
Clojure
16
star
30

sauna-todo

Simple full-stack TODO app example for demonstrating Clojure(script)
Clojure
16
star
31

packaging-clojure-examples

Packaging a full-stack Clojure web app for production
Clojure
16
star
32

loiste

Excellent Excel library
Clojure
16
star
33

clojure-bootcamp

Clojure
14
star
34

metosin-common

Random collection of various namespaces used in multiple Metosin projects
Clojure
13
star
35

viesti

Data-Driven Message Dispatcher for Clojure/Script
12
star
36

sormilla

Playing with Leap Motion and Parrot AR.Drone
Clojure
11
star
37

malli.io

Malli playground, https://malli.io
Clojure
11
star
38

lomakkeet

Proof of concept: Form library for Reagent
Clojure
11
star
39

c2

Demo about compojure-api2 stuff
Clojure
8
star
40

cloud-busting

Basis for using Terraform to manage application runtime in AWS
HCL
7
star
41

palikka

Opinionated component library
Clojure
7
star
42

tyylikas

Clojure linter and fixer
Clojure
6
star
43

oksa

Generate GraphQL queries using Clojure data structures.
Clojure
6
star
44

kekkonen-sample

Sample project With Kekkonen
Clojure
5
star
45

clojure-bootcamp-setup

Setup instructions for Metosin Clojure Bootcamp training
Clojure
5
star
46

web-schemas

Prismatic Schema extensions for the Web.
Clojure
5
star
47

compojure-intro

compojure-intro
Clojure
4
star
48

clj-suomi

A Clojure library designed to access Finnish code sets.
Clojure
4
star
49

lokit

Single dependency for logging on the JVM
Clojure
4
star
50

tom

Tom, a graph-based component library
Clojure
4
star
51

bootcamp-2019-04-08

Bootcamp 2019-04-08
Clojure
4
star
52

boot-deps-size

Boot task to check size of dependencies
Clojure
4
star
53

om-dev-tools

Clojure
4
star
54

compojure-api-template

Compojure Api Template
Clojure
4
star
55

bootcamp-2021-feb

Lessons and exercises for bootcamp in February 2021
Clojure
4
star
56

kekkonen-building-permit-example

a complex simulated real-life case example showcase project
Clojure
4
star
57

terraform-study-group

3
star
58

training-2023-05-32

Advanced Clojure training
Clojure
3
star
59

open-source

Home page for Metosin's open source development work
JavaScript
3
star
60

lein-simulflow

ABANDONED: Combine several lein auto tasks for leaner workflow.
Clojure
3
star
61

bootcamp-2018-03-15-sample-app

Sample app for bootcamp 2018-03-15
Clojure
3
star
62

linkit

Om.next + Kekkonen test
Clojure
3
star
63

clj-ai-meetup

Case Studies in AI for Clojure Tampere meetup
Clojure
3
star
64

bootcamp-2

Bootcamp 2
Clojure
2
star
65

bootcamp3

Refactored bootcamp
Clojure
2
star
66

clojure-koulutus-2023-01-24-esitehtavat

Clojure ja ClojureScript koulutus 2023-01-24 esitehtävät
Clojure
2
star
67

bootcamp-2018-05-04

Sample app for bootcamp at 2018-05-04
Clojure
2
star
68

clojure-bootcamp-20150130

Clojure Bootcamp 2015-01-30 for Affecto
Clojure
2
star
69

clojure-finland-2018-05-30-cljs-ws-demo

ClojureScript and WebSocket demo for Clojure Finland 2018-05-20 meetup
Clojure
2
star
70

juustometsae

vain käyttötarkoitus puuttuu
2
star
71

training-day-1

Example materials for first part of training
Clojure
2
star
72

2016-09-09-clojure-training

Material for 2016-09-09 intermediate Clojure training topics about Tooling and Workflow; and Full-stack apps
Clojure
2
star
73

postgres-tools

WIP Postgresql utilities
Clojure
2
star
74

boot-alt-http

Simple boot http server task to serve files from classpath.
Clojure
2
star
75

clojure-koulutus-2023-01-24

Koulutusmateriaali 2023-01-24 koulutukseen
Clojure
1
star
76

clojurebridge-intro

Intro project for ClojureBridge, in Finnish. Olkaa hyvä.
Clojure
1
star
77

clojure-bootcamp-intro

Bootcamp intro project
Clojure
1
star
78

reitit-example

Sample layout for reitit
Clojure
1
star
79

bootbook

BootBook :- Clojure Bootcamp book-store example
Clojure
1
star
80

docker-circle-convox

Dockerfile
1
star
81

docker-circle-lein

1
star
82

ks-example

Simple example project with clj and cljs
Clojure
1
star
83

rabbitmq-agent

Clojure
1
star
84

bootcamp-luminus-2021-feb

Luminus application for 2021 February bootcamp
Clojure
1
star
85

compojure-api-sample

Compojure-api sample project with Component
Clojure
1
star
86

2016-09-09-clojure-training-2

Material for 2016-09-09 intermediate Clojure training: perf, polymorfic, data, diy weblib
Clojure
1
star
87

clojurebridge-helsinki

Homepage for ClojureBridge Finland
CSS
1
star
88

bootcamp-20170314

Bootcamp example for 2017/03/14-16 bootcamp
Clojure
1
star
89

example-project

Clojure
1
star