reorganize module

_archive/rhai_engine/rhaibook/engine/dynamic-lib.md

@@ -0,0 +1,56 @@
+Use Rhai in Dynamic Libraries
+=============================
+
+{{#include ../links.md}}
+
+Sometimes functions registered into a Rhai [`Engine`] come from _dynamic libraries_ (a.k.a. _shared
+libraries_ in Linux or _DLL's_ in Windows), which are compiled separately from the main binary, not
+statically linked but loaded dynamically at runtime.
+
+~~~admonish example.small "`rhai-dylib`"
+
+The project [`rhai-dylib`] demonstrates an API for creating dynamically-loadable libraries
+for use with a Rhai [`Engine`].
+~~~
+
+
+Problem Symptom
+---------------
+
+The symptom is usually _Function Not Found_ errors even though the relevant functions (within the
+dynamic library) have already been registered into the [`Engine`].
+
+This usually happens when a mutable reference to the [`Engine`] is passed into an entry-point
+function exposed by the dynamic library and the [`Engine`]'s function registration API is called
+inside the dynamic library.
+
+
+Problem Cause
+-------------
+
+To counter [DOS] attacks, the _hasher_ used by Rhai, [`ahash`], automatically generates a different
+_seed_ for hashing during each compilation and execution run.
+
+This means that hash values generated by the hasher will not be _stable_ – they change
+during each compile, and during each run.
+
+This creates hash mismatches between the main binary and the loaded dynamic library because, as they
+are not linked together at compile time, two independent copies of the hasher reside in them,
+resulting in different hashes for even the same function signature.
+
+
+Solution
+--------
+
+Use [static hashing] for force predictable hashes.
+
+```admonish warning.small "Warning: Safety considerations"
+
+Static hashing allows dynamic libraries with Rhai code to be loaded and used with
+an [`Engine`] in the main binary.
+
+However, a fixed seed enlarges the attack surface of Rhai to malicious intent
+(e.g. [DOS] attacks).
+
+This safety trade-off should be carefully considered.
+```