luciano/nippy
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
nippy/taoensso.nippy.html

270 lines
38 KiB
HTML
Raw Normal View History

v2.11.0
2016-02-25 11:50:00 +00:00
<!DOCTYPE html PUBLIC ""
"">
v2.15.1
2020-07-25 07:39:40 +00:00
<html><head><meta charset="UTF-8" /><title>taoensso.nippy documentation</title><link rel="stylesheet" type="text/css" href="css/default.css" /><link rel="stylesheet" type="text/css" href="css/highlight.css" /><script type="text/javascript" src="js/highlight.min.js"></script><script type="text/javascript" src="js/jquery.min.js"></script><script type="text/javascript" src="js/page_effects.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body><div id="header"><h2>Generated by <a href="https://github.com/weavejester/codox">Codox</a></h2><h1><a href="index.html"><span class="project-title"><span class="project-name">Nippy</span> <span class="project-version">2.15.1</span></span></a></h1></div><div class="sidebar primary"><h3 class="no-link"><span class="inner">Project</span></h3><ul class="index-link"><li class="depth-1 "><a href="index.html"><div class="inner">Index</div></a></li></ul><h3 class="no-link"><span class="inner">Namespaces</span></h3><ul><li class="depth-1"><div class="no-link"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>taoensso</span></div></div></li><li class="depth-2 current"><a href="taoensso.nippy.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>nippy</span></div></a></li><li class="depth-3 branch"><a href="taoensso.nippy.benchmarks.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>benchmarks</span></div></a></li><li class="depth-3 branch"><a href="taoensso.nippy.compression.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>compression</span></div></a></li><li class="depth-3 branch"><a href="taoensso.nippy.crypto.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>crypto</span></div></a></li><li class="depth-3 branch"><a href="taoensso.nippy.encryption.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>encryption</span></div></a></li><li class="depth-3 branch"><a href="taoensso.nippy.tools.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>tools</span></div></a></li><li class="depth-3"><a href="taoensso.nippy.utils.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>utils</span></div></a></li></ul></div><div class="sidebar secondary"><h3><a href="#top"><span class="inner">Public Vars</span></a></h3><ul><li class="depth-1"><a href="taoensso.nippy.html#var-*auto-freeze-compressor*"><div class="inner"><span>*auto-freeze-compressor*</span></div></a></li><li class="depth-1"><a href="taoensso.nippy.html#var-*custom-readers*"><div class="inner"><span>*custom-readers*</span></div></a></li><li class="depth-1"><a href="taoensso.nippy.html#var-*final-freeze-fallback*"><div class="inner"><span>*final-freeze-fallback*</span></div></a></li><li class="depth-1"><a href="taoensso.nippy.html#var-*freeze-fallback*"><div class="inner"><span>*freeze-fallback*</span></div></a></li><li class="depth-1"><a href="taoensso.nippy.html#var-*incl-metadata.3F*"><div class="inner"><span>*incl-metadata?*</span></div></a></li><li class="depth-1"><a href="taoensso.nippy.html#var-*serializable-whitelist*"><div class="inner"><span>*serializable-whitelist*</span></div></a></li><li class="depth-1"><a href="taoensso.nippy.html#var--cache-proxy"><div class="inner"><span>-cache-proxy</span></div></a></li><li class="depth-1"><a href="taoensso.nippy.html#var-aes128-cbc-encryptor"><div class="inner"><span>aes128-cbc-encryptor</span></div></a></li><li class="depth-1"><a href="taoensso.nippy.html#var-aes128-encryptor"><div class="inner"><span>aes128-encryptor</span></div></a></li><li class="depth-1"><a href="taoensso.nippy.html#var-aes128-gcm-encryptor"><div class="inner"><span>aes128-gcm-encryptor</span></div></a></li><li class="depth-1"><a href="taoensso.nippy.html#
v2.12.0-beta1
2016-06-10 04:00:39 +00:00
</pre></div><div class="public anchor" id="var-*auto-freeze-compressor*"><h3>*auto-freeze-compressor*</h3><h4 class="dynamic">dynamic</h4><div class="usage"></div><div class="doc"><pre class="plaintext">(fn [byte-array])-&gt;compressor used by `(freeze &lt;x&gt; {:compressor :auto}),
v2.15.1
2020-07-25 07:39:40 +00:00
nil =&gt; default</pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L281">view source</a></div></div><div class="public anchor" id="var-*custom-readers*"><h3>*custom-readers*</h3><h4 class="dynamic">dynamic</h4><div class="usage"></div><div class="doc"><pre class="plaintext">{&lt;hash-or-byte-id&gt; (fn [data-input])-&gt;read}
</pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L280">view source</a></div></div><div class="public anchor" id="var-*final-freeze-fallback*"><h3>*final-freeze-fallback*</h3><h4 class="dynamic">dynamic</h4><div class="usage"></div><div class="doc"><pre class="plaintext">DEPRECATED: prefer `*freeze-fallback`.
</pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L277">view source</a></div></div><div class="public anchor" id="var-*freeze-fallback*"><h3>*freeze-fallback*</h3><h4 class="dynamic">dynamic</h4><div class="usage"></div><div class="doc"><pre class="plaintext">(fn [data-output x])-&gt;freeze, nil =&gt; default
</pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L278">view source</a></div></div><div class="public anchor" id="var-*incl-metadata.3F*"><h3>*incl-metadata?*</h3><h4 class="dynamic">dynamic</h4><div class="usage"></div><div class="doc"><pre class="plaintext">Include metadata when freezing/thawing?
</pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L286">view source</a></div></div><div class="public anchor" id="var-*serializable-whitelist*"><h3>*serializable-whitelist*</h3><h4 class="dynamic">dynamic</h4><div class="usage"></div><div class="doc"><pre class="plaintext">Used when attempting to freeze or thaw an object that:
v2.15.0
2020-07-24 18:40:46 +00:00
- Does not implement Nippy's Freezable protocol.
- Does implement Java's Serializable interface.
In this case, Java's Serializable interface will be permitted iff
the predicate (*serializable-whitelist* &lt;class-name&gt;) returns true.
v2.15.1
2020-07-25 07:39:40 +00:00
I.e. this is a predicate (fn allow-class? [class-name]) that specifies
whether Nippy may use a given class's Serializable implementation as
v2.15.0
2020-07-24 18:40:46 +00:00
fallback when its own protocol is unfamiliar with the type.
v2.15.1
2020-07-25 07:39:40 +00:00
If `thaw` encounters an unwhitelisted Serialized class:
- `thaw` will throw if it's not possible to safely quarantine.
- Otherwise the object will be thawed as:
`{:nippy/unthawable {:class-name _ :content &lt;quarantined-ba&gt; ...}}`.
v2.15.0
2020-07-24 18:40:46 +00:00
This is a security measure to prevent Remote Code Execution (RCE).
v2.15.1
2020-07-25 07:39:40 +00:00
Default value is a set containing a number of known-safe classes,
see `default-serializable-whitelist` for details. PRs welcome to add
additional known-safe classes to default.
Value may be overridden with `swap-serializable-whitelist!` or with:
- `taoensso.nippy.serializable-whitelist-base` JVM property
- `taoensso.nippy.serializable-whitelist-add` JVM property
- `TAOENSSO_NIPPY_SERIALIZABLE_WHITELIST_BASE` env var
- `TAOENSSO_NIPPY_SERIALIZABLE_WHITELIST_ADD` env var
If present, these will be read as comma-separated lists of class
names and formed into sets. Initial whitelist value will then be:
(into (or &lt;?base&gt; &lt;default&gt;) &lt;?additions&gt;).
I.e. you can use:
- The "base" property/var to override Nippy's default whitelist.
- The "add" property/var to add to Nippy's default whitelist.
Strings in sets may contain "*" wildcards.
See also `taoensso.encore/compile-str-filter`, a util to help
easily build more advanced predicate functions.
================
Further context:
v2.15.0
2020-07-24 18:40:46 +00:00
Reading arbitrary Serializable classes can be dangerous if they
come from an untrusted source.
v2.15.1
2020-07-25 07:39:40 +00:00
Specifically: if your classpath contains a vulnerable ("gadget")[2]
v2.15.0
2020-07-24 18:40:46 +00:00
class - it is possible for an attacker to produce an object that
can run arbitrary code when read via Serializable.
Note that Clojure &lt;= 1.8 itself contains such a class [1].
What to use as a whitelist?
1. If you DO NOT wish to support Serializable: `#{}` is safest,
and just entirely disallows its use.
2. If you DO with to support Serializable:
2a. If you might serialize data from an untrusted source, or
if you'll only be serializing a limited number of known
classes: enumerate those class names, e.g.:
`#{"java.lang.Throwable", ...}`.
2b. If you're CERTAIN to NEVER serialize data from an untrusted
source, you can use `(constantly true)` as predicate. This
will whitelist everything, allowing Serializable for ANY class.
v2.15.1
2020-07-25 07:39:40 +00:00
Upgrading from an older version of Nippy and not sure whether you've
been using Nippy's Serializable support? Here's a code snippet that
will allow AND RECORD any class using Nippy's Serializable fallback:
v2.15.0
2020-07-24 18:40:46 +00:00
v2.15.1
2020-07-25 07:39:40 +00:00
;; Deref for set of all class names that made use of Nippy's Serializable support:
(defonce observed-serializables_ (atom #{}))
v2.15.0
2020-07-24 18:40:46 +00:00
v2.15.1
2020-07-25 07:39:40 +00:00
(swap-serializable-whitelist!
(fn [_]
(fn allow-class? [class-name]
(swap! observed-serializables_ conj class-name) ; Record class name
true ; Allow any class
)))
v2.15.0
2020-07-24 18:40:46 +00:00
Thanks to Timo Mihaljov (@solita-timo-mihaljov) for an excellent report
identifying this vulnerability.
v2.15.1
2020-07-25 07:39:40 +00:00
[1] <a href="https://groups.google.com/forum/#!msg/clojure/WaL3hHzsevI/7zHU-L7LBQAJ">https://groups.google.com/forum/#!msg/clojure/WaL3hHzsevI/7zHU-L7LBQAJ</a>
[2] Jackson maintains a list of common gadget classes at
<a href="https://github.com/FasterXML/jackson-databind/blob/master/src/main/java/com/fasterxml/jackson/databind/jsontype/impl/SubTypeValidator.java">https://github.com/FasterXML/jackson-databind/blob/master/src/main/java/com/fasterxml/jackson/databind/jsontype/impl/SubTypeValidator.java</a></pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L304">view source</a></div></div><div class="public anchor" id="var--cache-proxy"><h3>-cache-proxy</h3><div class="usage"></div><div class="doc"><pre class="plaintext">{[&lt;x&gt; &lt;meta&gt;] &lt;idx&gt;} for freezing, {&lt;idx&gt; &lt;x-with-meta&gt;} for thawing.
</pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L917">view source</a></div></div><div class="public anchor" id="var-aes128-cbc-encryptor"><h3>aes128-cbc-encryptor</h3><div class="usage"></div><div class="doc"><pre class="plaintext">Default 128bit AES-CBC encryptor with many-round SHA-512 key-gen.
See also `aes-128-cbc-encryptor`.</pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L268">view source</a></div></div><div class="public anchor" id="var-aes128-encryptor"><h3>aes128-encryptor</h3><div class="usage"></div><div class="doc"><pre class="plaintext">Default 128bit AES-GCM encryptor with many-round SHA-512 key-gen.
v2.7.0-alpha1
2014-07-06 06:37:03 +00:00
v2.11.0
2016-02-25 11:50:00 +00:00
Password form [:salted "my-password"]
v2.7.0-alpha1
2014-07-06 06:37:03 +00:00
---------------------------------------
USE CASE: You want more than a small, finite number of passwords (e.g. each
v2.10.0-beta1
2015-09-17 04:19:19 +00:00
item encrypted will use a unique user-provided password).
v2.7.0-alpha1
2014-07-06 06:37:03 +00:00
IMPLEMENTATION: Uses a relatively cheap key hash, but automatically salts
every key.
PROS: Each key is independent so would need to be attacked independently.
v2.11.0
2016-02-25 11:50:00 +00:00
CONS: Key caching impossible, so there's an inherent trade-off between
v2.7.0-alpha1
2014-07-06 06:37:03 +00:00
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.
v2.11.0
2016-02-25 11:50:00 +00:00
Password form [:cached "my-password"]
v2.7.0-alpha1
2014-07-06 06:37:03 +00:00
---------------------------------------
USE CASE: You want only a small, finite number of passwords (e.g. a limited
v2.11.0
2016-02-25 11:50:00 +00:00
number of staff/admins, or you'll be using a single password to
v2.7.0-alpha1
2014-07-06 06:37:03 +00:00
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
v2.15.1
2020-07-25 07:39:40 +00:00
increased danger if a key is somehow compromised.</pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L269">view source</a></div></div><div class="public anchor" id="var-aes128-gcm-encryptor"><h3>aes128-gcm-encryptor</h3><div class="usage"></div><div class="doc"><pre class="plaintext">Default 128bit AES-GCM encryptor with many-round SHA-512 key-gen.
v2.15.0
2020-07-24 18:40:46 +00:00
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
v2.15.1
2020-07-25 07:39:40 +00:00
increased danger if a key is somehow compromised.</pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L267">view source</a></div></div><div class="public anchor" id="var-cache"><h3>cache</h3><div class="usage"><code>(cache x)</code></div><div class="doc"><pre class="plaintext">Experimental, subject to change.
v2.12.0-RC2
2016-07-17 08:48:36 +00:00
Wraps value so that future writes of the same wrapped value with same
metadata will be efficiently encoded as references to this one.
v2.12.0-beta1
2016-06-10 04:00:39 +00:00
(freeze [(cache "foo") (cache "foo") (cache "foo")])
v2.15.1
2020-07-25 07:39:40 +00:00
will incl. a single "foo", plus 2x single-byte references to "foo".</pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L936">view source</a></div></div><div class="public anchor" id="var-compress"><h3>compress</h3><div class="usage"><code>(compress compressor ba)</code></div><div class="doc"><pre class="plaintext"></pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L257">view source</a></div></div><div class="public anchor" id="var-decompress"><h3>decompress</h3><div class="usage"><code>(decompress compressor ba)</code></div><div class="doc"><pre class="plaintext"></pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L258">view source</a></div></div><div class="public anchor" id="var-decrypt"><h3>decrypt</h3><div class="usage"><code>(decrypt encryptor pwd ba)</code></div><div class="doc"><pre class="plaintext"></pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L265">view source</a></div></div><div class="public anchor" id="var-default-serializable-whitelist"><h3>default-serializable-whitelist</h3><div class="usage"></div><div class="doc"><pre class="plaintext">PRs welcome to add additional known-safe classes to default.
</pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L288">view source</a></div></div><div class="public anchor" id="var-encrypt"><h3>encrypt</h3><div class="usage"><code>(encrypt encryptor pwd ba)</code></div><div class="doc"><pre class="plaintext"></pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L264">view source</a></div></div><div class="public anchor" id="var-extend-freeze"><h3>extend-freeze</h3><h4 class="type">macro</h4><div class="usage"><code>(extend-freeze type custom-type-id [x out] &amp; body)</code></div><div class="doc"><pre class="plaintext">Extends Nippy to support freezing of a custom type (ideally concrete) with
v2.7.0-alpha1
2014-07-06 06:37:03 +00:00
given id of form:
v2.15.1
2020-07-25 07:39:40 +00:00
* Keyword - 2 byte overhead, keywords hashed to 16 bit id
* ℕ∈[1, 128] - 0 byte overhead
v2.7.0-alpha1
2014-07-06 06:37:03 +00:00
v2.12.0-RC2
2016-07-17 08:48:36 +00:00
NB: be careful about extending to interfaces, Ref. <a href="http://goo.gl/6gGRlU">http://goo.gl/6gGRlU</a>.
(defrecord MyRec [data])
(extend-freeze MyRec :foo/my-type [x data-output] ; Keyword id
v2.7.0-alpha1
2014-07-06 06:37:03 +00:00
(.writeUTF [data-output] (:data x)))
;; or
v2.12.0-RC2
2016-07-17 08:48:36 +00:00
(extend-freeze MyRec 1 [x data-output] ; Byte id
v2.15.1
2020-07-25 07:39:40 +00:00
(.writeUTF [data-output] (:data x)))</pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L1741">view source</a></div></div><div class="public anchor" id="var-extend-thaw"><h3>extend-thaw</h3><h4 class="type">macro</h4><div class="usage"><code>(extend-thaw custom-type-id [in] &amp; body)</code></div><div class="doc"><pre class="plaintext">Extends Nippy to support thawing of a custom type with given id:
v2.7.0-alpha1
2014-07-06 06:37:03 +00:00
(extend-thaw :foo/my-type [data-input] ; Keyword id
v2.12.0-RC2
2016-07-17 08:48:36 +00:00
(MyRec. (.readUTF data-input)))
v2.7.0-alpha1
2014-07-06 06:37:03 +00:00
;; or
(extend-thaw 1 [data-input] ; Byte id
v2.15.1
2020-07-25 07:39:40 +00:00
(MyRec. (.readUTF data-input)))</pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L1772">view source</a></div></div><div class="public anchor" id="var-fast-freeze"><h3>fast-freeze</h3><div class="usage"><code>(fast-freeze x)</code><code>(fast-freeze x opts)</code></div><div class="doc"><pre class="plaintext">Like `freeze` but:
v2.12.0-beta1
2016-06-10 04:00:39 +00:00
- Writes data without a Nippy header
- Drops all support for compression and encryption
- Must be thawed with `fast-thaw`
Equivalent to (but a little faster than):
v2.15.1
2020-07-25 07:39:40 +00:00
`(freeze x {:compressor nil :encryptor nil :no-header? true})</pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L1171">view source</a></div></div><div class="public anchor" id="var-fast-thaw"><h3>fast-thaw</h3><div class="usage"><code>(fast-thaw ba)</code><code>(fast-thaw ba opts)</code></div><div class="doc"><pre class="plaintext">Like `thaw` but:
v2.12.0-beta1
2016-06-10 04:00:39 +00:00
- Drops all support for compression and encryption
- Supports only data frozen with `fast-freeze`
Equivalent to (but a little faster than):
v2.15.1
2020-07-25 07:39:40 +00:00
`(thaw x {:compressor nil :encryptor nil :no-header? true})</pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L1600">view source</a></div></div><div class="public anchor" id="var-freezable.3F"><h3>freezable?</h3><div class="usage"><code>(freezable? x)</code><code>(freezable? x {:keys [allow-clojure-reader? allow-java-serializable?]})</code></div><div class="doc"><pre class="plaintext">Alpha - subject to change.
v2.12.0-beta1
2016-06-10 04:00:39 +00:00
Returns truthy iff Nippy *appears* to support freezing the given argument.
`:allow-clojure-reader?` and `:allow-java-serializable?` options may be
used to 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 value equality (there's no good general
v2.15.1
2020-07-25 07:39:40 +00:00
way of doing so).</pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L271">view source</a></div></div><div class="public anchor" id="var-freeze"><h3>freeze</h3><div class="usage"><code>(freeze x)</code><code>(freeze x {:as opts, :keys [compressor encryptor password serializable-whitelist incl-metadata?], :or {compressor :auto, encryptor aes128-gcm-encryptor}})</code></div><div class="doc"><pre class="plaintext">Serializes arg (any Clojure data type) to a byte array. To freeze custom
types, extend the Clojure reader or see `extend-freeze`.</pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L1188">view source</a></div></div><div class="public anchor" id="var-freeze-fallback-as-str"><h3>freeze-fallback-as-str</h3><div class="usage"></div><div class="doc"><pre class="plaintext">DEPRECATED
</pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L1966">view source</a></div></div><div class="public anchor" id="var-freeze-to-file"><h3>freeze-to-file</h3><div class="usage"><code>(freeze-to-file file x)</code><code>(freeze-to-file file x freeze-opts)</code></div><div class="doc"><pre class="plaintext">Convenience util: like `freeze`, but writes to `(clojure.java.io/file &lt;file&gt;)`
v2.15.0
2020-07-24 18:40:46 +00:00
and returns the byte array written.
v2.15.1
2020-07-25 07:39:40 +00:00
See also `thaw-from-file`.</pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L1932">view source</a></div></div><div class="public anchor" id="var-freeze-to-out.21"><h3>freeze-to-out!</h3><div class="usage"><code>(freeze-to-out! data-output x)</code></div><div class="doc"><pre class="plaintext">Serializes arg (any Clojure data type) to a DataOutput.
This is a low-level util: in most cases you'll want `freeze` instead.</pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L896">view source</a></div></div><div class="public anchor" id="var-freeze-to-string"><h3>freeze-to-string</h3><div class="usage"><code>(freeze-to-string x)</code><code>(freeze-to-string x freeze-opts)</code></div><div class="doc"><pre class="plaintext">Convenience util: like `freeze`, but returns a Base64-encoded string.
See also `thaw-from-string`.</pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L1913">view source</a></div></div><div class="public anchor" id="var-IFreezable1"><h3>IFreezable1</h3><h4 class="type">protocol</h4><div class="usage"></div><div class="doc"><pre class="plaintext"></pre></div><div class="members"><h4>members</h4><div class="inner"><div class="public anchor" id="var--freeze-without-meta.21"><h3>-freeze-without-meta!</h3><div class="usage"><code>(-freeze-without-meta! x data-output)</code></div><div class="doc"><pre class="plaintext"></pre></div></div></div></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L461">view source</a></div></div><div class="public anchor" id="var-IFreezable2"><h3>IFreezable2</h3><h4 class="type">protocol</h4><div class="usage"></div><div class="doc"><pre class="plaintext"></pre></div><div class="members"><h4>members</h4><div class="inner"><div class="public anchor" id="var--freeze-with-meta.21"><h3>-freeze-with-meta!</h3><div class="usage"><code>(-freeze-with-meta! x data-output)</code></div><div class="doc"><pre class="plaintext"></pre></div></div></div></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L462">view source</a></div></div><div class="public anchor" id="var-inspect-ba"><h3>inspect-ba</h3><div class="usage"><code>(inspect-ba ba)</code><code>(inspect-ba ba thaw-opts)</code></div><div class="doc"><pre class="plaintext">Alpha - subject to change
</pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L1885">view source</a></div></div><div class="public anchor" id="var-lz4-compressor"><h3>lz4-compressor</h3><div class="usage"></div><div class="doc"><pre class="plaintext">Default net.jpountz.lz4 compressor:
v2.7.0-alpha1
2014-07-06 06:37:03 +00:00
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,
v2.15.1
2020-07-25 07:39:40 +00:00
Ref. <a href="https://github.com/mpenet/nippy-lz4">https://github.com/mpenet/nippy-lz4</a></pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L261">view source</a></div></div><div class="public anchor" id="var-lz4hc-compressor"><h3>lz4hc-compressor</h3><div class="usage"></div><div class="doc"><pre class="plaintext">Like `lz4-compressor` but trades some write speed for ratio.
</pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L262">view source</a></div></div><div class="public anchor" id="var-lzma2-compressor"><h3>lzma2-compressor</h3><div class="usage"></div><div class="doc"><pre class="plaintext">Default org.tukaani.xz.LZMA2 compressor:
v2.7.0-alpha1
2014-07-06 06:37:03 +00:00
Ratio: high.
Write speed: _very_ slow (also currently single-threaded).
Read speed: slow.
A specialized compressor for large, low-write data in space-sensitive
v2.15.1
2020-07-25 07:39:40 +00:00
environments.</pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L260">view source</a></div></div><div class="public anchor" id="var-set-auto-freeze-compressor.21"><h3>set-auto-freeze-compressor!</h3><div class="usage"><code>(set-auto-freeze-compressor! x)</code></div><div class="doc"><pre class="plaintext"></pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L427">view source</a></div></div><div class="public anchor" id="var-set-freeze-fallback.21"><h3>set-freeze-fallback!</h3><div class="usage"><code>(set-freeze-fallback! x)</code></div><div class="doc"><pre class="plaintext"></pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L426">view source</a></div></div><div class="public anchor" id="var-snappy-compressor"><h3>snappy-compressor</h3><div class="usage"></div><div class="doc"><pre class="plaintext">Default org.iq80.snappy.Snappy compressor:
v2.7.0-alpha1
2014-07-06 06:37:03 +00:00
Ratio: low.
Write speed: very high.
Read speed: very high.
v2.15.1
2020-07-25 07:39:40 +00:00
A good general-purpose compressor.</pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L259">view source</a></div></div><div class="public anchor" id="var-stress-data"><h3>stress-data</h3><div class="usage"></div><div class="doc"><pre class="plaintext">Reference data used for tests &amp; benchmarks
</pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L1805">view source</a></div></div><div class="public anchor" id="var-stress-data-benchable"><h3>stress-data-benchable</h3><div class="usage"></div><div class="doc"><pre class="plaintext">Reference data with stuff removed that breaks reader or other utils we'll
be benching against</pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L1876">view source</a></div></div><div class="public anchor" id="var-stress-data-comparable"><h3>stress-data-comparable</h3><div class="usage"></div><div class="doc"><pre class="plaintext">Reference data with stuff removed that breaks roundtrip equality
</pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L1872">view source</a></div></div><div class="public anchor" id="var-swap-custom-readers.21"><h3>swap-custom-readers!</h3><div class="usage"><code>(swap-custom-readers! f)</code></div><div class="doc"><pre class="plaintext"></pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L428">view source</a></div></div><div class="public anchor" id="var-swap-serializable-whitelist.21"><h3>swap-serializable-whitelist!</h3><div class="usage"><code>(swap-serializable-whitelist! f)</code></div><div class="doc"><pre class="plaintext">Changes root `*serializable-whitelist*` value to (f old-val).
v2.15.0
2020-07-24 18:40:46 +00:00
Example `f` arguments:
- (fn [_old] true) ; Whitelist everything (allow all classes)
- (fn [_old] #{}) ; Whitelist nothing (disallow all classes)
v2.15.1
2020-07-25 07:39:40 +00:00
- (fn [_old] #{"java.lang.Throwable"}) ; Reset class whitelist set
- (fn [ old] (conj old "java.lang.Throwable"))) ; Add class to whitelist set
- (fn [ old] (conj old "java.lang.*")) ; Add classes to whitelist set (note wildcard)
Strings in sets may contain "*" wildcards.
v2.15.0
2020-07-24 18:40:46 +00:00
v2.15.1
2020-07-25 07:39:40 +00:00
See also `*serializable-whitelist*.</pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L429">view source</a></div></div><div class="public anchor" id="var-thaw"><h3>thaw</h3><div class="usage"><code>(thaw ba)</code><code>(thaw ba {:as opts, :keys [v1-compatibility? compressor encryptor password serializable-whitelist incl-metadata?], :or {compressor :auto, encryptor :auto}})</code></div><div class="doc"><pre class="plaintext">Deserializes a frozen Nippy byte array to its original Clojure data type.
v2.12.0-beta1
2016-06-10 04:00:39 +00:00
To thaw custom types, extend the Clojure reader or see `extend-thaw`.
v2.11.0-alpha1
2015-12-01 06:06:24 +00:00
** By default, supports data frozen with Nippy v2+ ONLY **
Add `{:v1-compatibility? true}` option to support thawing of data frozen with
legacy versions of Nippy.
v2.7.0-alpha1
2014-07-06 06:37:03 +00:00
Options include:
v2.11.0-alpha1
2015-12-01 06:06:24 +00:00
:v1-compatibility? - support data frozen by legacy versions of Nippy?
:compressor - :auto (checks header, default) an ICompressor, or nil
v2.15.1
2020-07-25 07:39:40 +00:00
:encryptor - :auto (checks header, default), an IEncryptor, or nil</pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L1615">view source</a></div></div><div class="public anchor" id="var-thaw-from-file"><h3>thaw-from-file</h3><div class="usage"><code>(thaw-from-file file)</code><code>(thaw-from-file file thaw-opts)</code></div><div class="doc"><pre class="plaintext">Convenience util: like `thaw`, but reads from `(clojure.java.io/file &lt;file&gt;)`.
v2.13.0
2017-02-13 17:01:34 +00:00
To thaw from a resource on classpath (e.g in Leiningen `resources` dir):
v2.15.0
2020-07-24 18:40:46 +00:00
(thaw-from-file (clojure.java.io/resource "my-resource-name.npy"))
v2.15.1
2020-07-25 07:39:40 +00:00
See also `freeze-to-file`.</pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L1943">view source</a></div></div><div class="public anchor" id="var-thaw-from-in.21"><h3>thaw-from-in!</h3><div class="usage"><code>(thaw-from-in! data-input)</code></div><div class="doc"><pre class="plaintext">Deserializes a frozen object from given DataInput to its original Clojure
v2.12.0-RC2
2016-07-17 08:48:36 +00:00
data type.
v2.15.1
2020-07-25 07:39:40 +00:00
This is a low-level util: in most cases you'll want `thaw` instead.</pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L1411">view source</a></div></div><div class="public anchor" id="var-thaw-from-string"><h3>thaw-from-string</h3><div class="usage"><code>(thaw-from-string s)</code><code>(thaw-from-string s thaw-opts)</code></div><div class="doc"><pre class="plaintext">Convenience util: like `thaw`, but takes a Base64-encoded string.
See also `freeze-to-string`.</pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L1922">view source</a></div></div><div class="public anchor" id="var-throw-unfreezable"><h3>throw-unfreezable</h3><div class="usage"><code>(throw-unfreezable x)</code></div><div class="doc"><pre class="plaintext"></pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L889">view source</a></div></div><div class="public anchor" id="var-try-write-readable"><h3>try-write-readable</h3><div class="usage"><code>(try-write-readable out x)</code></div><div class="doc"><pre class="plaintext"></pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L868">view source</a></div></div><div class="public anchor" id="var-try-write-serializable"><h3>try-write-serializable</h3><div class="usage"><code>(try-write-serializable out x)</code></div><div class="doc"><pre class="plaintext"></pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L859">view source</a></div></div><div class="public anchor" id="var-write-id"><h3>write-id</h3><h4 class="type">macro</h4><div class="usage"><code>(write-id out id)</code></div><div class="doc"><pre class="plaintext"></pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L447">view source</a></div></div><div class="public anchor" id="var-write-unfreezable"><h3>write-unfreezable</h3><div class="usage"><code>(write-unfreezable out x)</code></div><div class="doc"><pre class="plaintext"></pre></div><div class="src-link"><a href="https://github.com/ptaoussanis/nippy/blob/master/src/taoensso/nippy.clj#L883">view source</a></div></div></div></body></html>
Reference in a new issue Copy permalink