Nippy 2.9.0-beta2 API documentation

Alpha - subject to change.

Positional factory function for class taoensso.nippy.Compressable-LZMA2.

Positional factory function for class taoensso.nippy.StressRecord.

Default 128bit AES encryptor with multi-round SHA-512 key-gen.

Password form [:salted "my-password"]
---------------------------------------
USE CASE: You want more than a small, finite number of passwords (e.g. each
           item encrypted will use a unique user-provided password).

IMPLEMENTATION: Uses a relatively cheap key hash, but automatically salts
                every key.

PROS: Each key is independent so would need to be attacked independently.
CONS: Key caching impossible, so there's an inherent trade-off between
      encryption/decryption speed and the difficulty of attacking any
      particular key.

Slower than `aes128-cached`, and easier to attack any particular key - but
keys are independent.

Password form [:cached "my-password"]
---------------------------------------
USE CASE: You want only a small, finite number of passwords (e.g. a limited
          number of staff/admins, or you'll be using a single password to
          encrypt many items).

IMPLEMENTATION: Uses a _very_ expensive (but cached) key hash, and no salt.

PROS: Great amortized encryption/decryption speed. Expensive key hash makes
      attacking any particular key very difficult.
CONS: Using a small number of keys for many encrypted items means that if any
      key _is_ somehow compromised, _all_ items encrypted with that key are
      compromised.

Faster than `aes128-salted`, and harder to attack any particular key - but
increased danger if a key is somehow compromised.

Strategy:
* Prioritize speed, but allow lz4.
* Skip lz4 unless it's likely that lz4's space benefit will outweigh its
  space overhead.

EXPERIMENTAL.
Determines the global default default compressor selector
(fn [^bytes ba])->compressor used by `(freeze <x> {:compressor :auto <...>}).

Extends Nippy to support freezing of a custom type (ideally concrete) with
given id of form:
  * Keyword        - 2 byte overhead, resistent to id collisions.
  * Byte ∈[1, 128] - no overhead, subject to id collisions.

(defrecord MyType [data])
(extend-freeze MyType :foo/my-type [x data-output] ; Keyword id
  (.writeUTF [data-output] (:data x)))
;; or
(extend-freeze MyType 1 [x data-output] ; Byte id
  (.writeUTF [data-output] (:data x)))

Extends Nippy to support thawing of a custom type with given id:
(extend-thaw :foo/my-type [data-input] ; Keyword id
  (->MyType (.readUTF data-input)))
;; or
(extend-thaw 1 [data-input] ; Byte id
  (->MyType (.readUTF data-input)))

Be careful about extending to interfaces, Ref. http://goo.gl/6gGRlU.

Alpha - subject to change, MAY BE BUGGY!
Returns truthy value iff Nippy supports de/serialization of given argument.
Conservative with default options.

`:allow-clojure-reader?` and `:allow-java-serializable?` options may be used
to also enable the relevant roundtrip fallback test(s). These tests are only
**moderately reliable** since they're cached by arg type and don't test for
pre/post serialization equality (there's no good general way of doing so).

Serializes arg (any Clojure data type) to a byte array. To freeze custom
types, extend the Clojure reader or see `extend-freeze`.

Alpha-subject to change.

Low-level API. Serializes arg (any Clojure data type) to a DataOutput.

DEPRECATED: Use `freeze-to-out!` instead.

Alpha - subject to change.

Default net.jpountz.lz4 compressor:
      Ratio: low.
Write speed: very high.
 Read speed: very high.

A good general-purpose compressor, competitive with Snappy.

Thanks to Max Penet (@mpenet) for our first implementation,
Ref. https://github.com/mpenet/nippy-lz4

Like `lz4-compressor` but trades some write speed for ratio.

Default org.tukaani.xz.LZMA2 compressor:
      Ratio: high.
Write speed: _very_ slow (also currently single-threaded).
 Read speed: slow.

A specialized compressor for large, low-write data in space-sensitive
environments.

Factory function for class taoensso.nippy.Compressable-LZMA2, taking a map of keywords to field values.

Factory function for class taoensso.nippy.StressRecord, taking a map of keywords to field values.

Default org.iq80.snappy.Snappy compressor:
      Ratio: low.
Write speed: very high.
 Read speed: very high.

A good general-purpose compressor.

Reference data used for tests & benchmarks.

Reference data with stuff removed that breaks reader or other utils we'll
be benching against.

Reference data with stuff removed that breaks roundtrip equality.

Deserializes a frozen object from given byte array to its original Clojure
data type. Supports data frozen with current and all previous versions of
Nippy. To thaw custom types, extend the Clojure reader or see `extend-thaw`.

Options include:
  :compressor - An ICompressor, :auto (requires Nippy header), or nil.
  :encryptor  - An IEncryptor,  :auto (requires Nippy header), or nil.

Low-level API. Deserializes a frozen object from given DataInput to its
original Clojure data type.

DEPRECATED: Use `thaw-from-in!` instead.

Uses 2->9 bytes.