| 1 | # Wombat
|
| 2 |
|
| 3 | Wombat is a standalone client-side URL rewriting system that performs the
|
| 4 | rewrites through targeted JavaScript overrides.
|
| 5 |
|
| 6 | Wombat was originally included in and distributed as part of [pywb](https://github.com/webrecorder/pywb)
|
| 7 | but has now been refactored and split off into this module for improved maintenance.
|
| 8 |
|
| 9 | pywb release >=2.3 rely on this standalone module. This standalone
|
| 10 | module now includes a thorough testing suite that checks for the correctness of
|
| 11 | the overrides with respect to web standards.
|
| 12 |
|
| 13 | The remaining portions of this documentation covers the development and
|
| 14 | testing of the library, as well as, the
|
| 15 | creation of the system from library.
|
| 16 |
|
| 17 | Before we continue, please note the following terminology:
|
| 18 |
|
| 19 | - `bundle`
|
| 20 | A single file that is the result of concatenating multiple source
|
| 21 | files into a single file
|
| 22 |
|
| 23 | - `bundle entry point`
|
| 24 | The root file that imports all additional functionality required to
|
| 25 | produce the resulting bundle
|
| 26 |
|
| 27 | ## Components
|
| 28 |
|
| 29 | The Wombat client-side URL rewriting system is comprised of three files
|
| 30 | (bundles)
|
| 31 |
|
| 32 | - `wombat.js`
|
| 33 | - `wombatProxyMode.js`
|
| 34 | - `wombatWorkers.js`
|
| 35 |
|
| 36 | These files are located in the static directory of pywb and are
|
| 37 | generated as part of the library's build step.
|
| 38 |
|
| 39 | The library can be found in the `wombat` directory located in the root
|
| 40 | of the projects repository (i.e. `pywb/wombat`).
|
| 41 |
|
| 42 | **Note**: We do not go into details of each file included in a bundle as
|
| 43 | those details are out of the scope of this documentation and ask those
|
| 44 | interested to consult the documentation included in each files source
|
| 45 | code.
|
| 46 |
|
| 47 | **wombat.js**
|
| 48 |
|
| 49 | This bundle is the primary bundle of Wombat as it is used in both
|
| 50 | non-proxy recording and replay.
|
| 51 |
|
| 52 | The entry point for this bundle is
|
| 53 | `src/wbWombat.js`.
|
| 54 |
|
| 55 | An representation of the bundles contents is shown below.
|
| 56 |
|
| 57 | wbWombat.js
|
| 58 | - wombat.js
|
| 59 | - funcMap.js
|
| 60 | - customStorage.js
|
| 61 | - wombatLocation.js
|
| 62 | - listeners.js
|
| 63 | - autoFetchWorker.js
|
| 64 |
|
| 65 | **wombatProxyMode.js**
|
| 66 |
|
| 67 | This bundle is an stripped down version of
|
| 68 | `wombat.js` that applies a minimal set of
|
| 69 | overrides to the browsers JavaScript APIs in order to facilitate pywb's
|
| 70 | proxy recording mode
|
| 71 |
|
| 72 | The entry point for this bundle is
|
| 73 | `src/wbWombatProxyMode.js`
|
| 74 |
|
| 75 | An representation of the bundles contents is shown below.
|
| 76 |
|
| 77 | wbWombatProxyMode.js
|
| 78 | - wombatLite.js
|
| 79 | - autoFetchWorkerProxyMode.js
|
| 80 |
|
| 81 | **wombatWorkers.js**
|
| 82 |
|
| 83 | This bundle is not a bundle per say but rather a flat file that applies
|
| 84 | the minimal set of overrides necessary to ensure that JavaScript web and
|
| 85 | service worker's operate as expected in both non-proxy recording and
|
| 86 | replay.
|
| 87 |
|
| 88 |
|
| 89 |
|