Copy docs into Zeek repo directly

This is based on commit 2731def9159247e6da8a3191783c89683363689c from the
zeek-docs repo.

doc/scripts/base/frameworks/storage/__load__.zeek.rst

@@ -0,0 +1,14 @@
+:tocdepth: 3
+
+base/frameworks/storage/__load__.zeek
+=====================================
+
+
+:Imports: :doc:`base/frameworks/storage/async.zeek </scripts/base/frameworks/storage/async.zeek>`, :doc:`base/frameworks/storage/main.zeek </scripts/base/frameworks/storage/main.zeek>`, :doc:`base/frameworks/storage/sync.zeek </scripts/base/frameworks/storage/sync.zeek>`
+
+Summary
+~~~~~~~
+
+Detailed Interface
+~~~~~~~~~~~~~~~~~~
+

doc/scripts/base/frameworks/storage/async.zeek.rst

@@ -0,0 +1,132 @@
+:tocdepth: 3
+
+base/frameworks/storage/async.zeek
+==================================
+.. zeek:namespace:: Storage::Async
+
+Asynchronous operation methods for the storage framework.
+
+:Namespace: Storage::Async
+:Imports: :doc:`base/frameworks/storage/main.zeek </scripts/base/frameworks/storage/main.zeek>`
+
+Summary
+~~~~~~~
+Functions
+#########
+=============================================================== ==============================================================================
+:zeek:id:`Storage::Async::close_backend`: :zeek:type:`function` Closes an existing backend connection asynchronously.
+:zeek:id:`Storage::Async::erase`: :zeek:type:`function`         Erases an entry from the backend asynchronously.
+:zeek:id:`Storage::Async::get`: :zeek:type:`function`           Gets an entry from the backend asynchronously.
+:zeek:id:`Storage::Async::open_backend`: :zeek:type:`function`  Opens a new backend connection based on a configuration object asynchronously.
+:zeek:id:`Storage::Async::put`: :zeek:type:`function`           Inserts a new entry into a backend asynchronously.
+=============================================================== ==============================================================================
+
+
+Detailed Interface
+~~~~~~~~~~~~~~~~~~
+Functions
+#########
+.. zeek:id:: Storage::Async::close_backend
+   :source-code: base/frameworks/storage/async.zeek 91 97
+
+   :Type: :zeek:type:`function` (backend: :zeek:type:`opaque` of Storage::BackendHandle) : :zeek:type:`Storage::OperationResult`
+
+   Closes an existing backend connection asynchronously. This method must be
+   called via a :zeek:see:`when` condition or an error will be returned.
+   
+
+   :param backend: A handle to a backend connection.
+   
+
+   :returns: A record containing the status of the operation and an optional error
+            string for failures.
+
+.. zeek:id:: Storage::Async::erase
+   :source-code: base/frameworks/storage/async.zeek 120 126
+
+   :Type: :zeek:type:`function` (backend: :zeek:type:`opaque` of Storage::BackendHandle, key: :zeek:type:`any`) : :zeek:type:`Storage::OperationResult`
+
+   Erases an entry from the backend asynchronously. This method must be called via
+   a :zeek:see:`when` condition or an error will be returned.
+   
+
+   :param backend: A handle to a backend connection.
+   
+
+   :param key: The key to erase.
+   
+
+   :returns: A record containing the status of the operation and an optional error
+            string for failures.
+
+.. zeek:id:: Storage::Async::get
+   :source-code: base/frameworks/storage/async.zeek 111 117
+
+   :Type: :zeek:type:`function` (backend: :zeek:type:`opaque` of Storage::BackendHandle, key: :zeek:type:`any`) : :zeek:type:`Storage::OperationResult`
+
+   Gets an entry from the backend asynchronously. This method must be called via a
+   :zeek:see:`when` condition or an error will be returned.
+   
+
+   :param backend: A handle to a backend connection.
+   
+
+   :param key: The key to look up.
+   
+
+   :returns: A record containing the status of the operation, an optional error
+            string for failures, and an optional value for success. The value
+            returned here will be of the type passed into
+            :zeek:see:`Storage::Async::open_backend`.
+
+.. zeek:id:: Storage::Async::open_backend
+   :source-code: base/frameworks/storage/async.zeek 82 88
+
+   :Type: :zeek:type:`function` (btype: :zeek:type:`Storage::Backend`, options: :zeek:type:`Storage::BackendOptions`, key_type: :zeek:type:`any`, val_type: :zeek:type:`any`) : :zeek:type:`Storage::OperationResult`
+
+   Opens a new backend connection based on a configuration object asynchronously.
+   This method must be called via a :zeek:see:`when` condition or an error will
+   be returned.
+   
+
+   :param btype: A tag indicating what type of backend should be opened. These are
+          defined by the backend plugins loaded.
+   
+
+   :param options: A record containing the configuration for the connection.
+   
+
+   :param key_type: The script-level type of keys stored in the backend. Used for
+             validation of keys passed to other framework methods.
+   
+
+   :param val_type: The script-level type of keys stored in the backend. Used for
+             validation of values passed to :zeek:see:`Storage::Async::put` as
+             well as for type conversions for return values from
+             :zeek:see:`Storage::Async::get`.
+   
+
+   :returns: A record containing the status of the operation, and either an error
+            string on failure or a value on success. The value returned here will
+            be an ``opaque of BackendHandle``.
+
+.. zeek:id:: Storage::Async::put
+   :source-code: base/frameworks/storage/async.zeek 100 108
+
+   :Type: :zeek:type:`function` (backend: :zeek:type:`opaque` of Storage::BackendHandle, args: :zeek:type:`Storage::PutArgs`) : :zeek:type:`Storage::OperationResult`
+
+   Inserts a new entry into a backend asynchronously. This method must be called
+   via a :zeek:see:`when` condition or an error will be returned.
+   
+
+   :param backend: A handle to a backend connection.
+   
+
+   :param args: A :zeek:see:`Storage::PutArgs` record containing the arguments for the
+         operation.
+   
+
+   :returns: A record containing the status of the operation and an optional error
+            string for failures.
+
+

doc/scripts/base/frameworks/storage/index.rst

@@ -0,0 +1,21 @@
+:orphan:
+
+Package: base/frameworks/storage
+================================
+
+
+:doc:`/scripts/base/frameworks/storage/__load__.zeek`
+
+
+:doc:`/scripts/base/frameworks/storage/async.zeek`
+
+   Asynchronous operation methods for the storage framework.
+
+:doc:`/scripts/base/frameworks/storage/main.zeek`
+
+   The storage framework provides a way to store long-term data to disk.
+
+:doc:`/scripts/base/frameworks/storage/sync.zeek`
+
+   Synchronous operation methods for the storage framework.
+

doc/scripts/base/frameworks/storage/main.zeek.rst

@@ -0,0 +1,140 @@
+:tocdepth: 3
+
+base/frameworks/storage/main.zeek
+=================================
+.. zeek:namespace:: Storage
+
+The storage framework provides a way to store long-term data to disk.
+
+:Namespace: Storage
+
+Summary
+~~~~~~~
+Redefinable Options
+###################
+================================================================================== =
+:zeek:id:`Storage::default_forced_sync`: :zeek:type:`bool` :zeek:attr:`&redef`     
+:zeek:id:`Storage::latency_metric_bounds`: :zeek:type:`vector` :zeek:attr:`&redef` 
+================================================================================== =
+
+Types
+#####
+========================================================= ===================================================================
+:zeek:type:`Storage::BackendOptions`: :zeek:type:`record` Base record for backend options that can be passed to
+                                                          :zeek:see:`Storage::Async::open_backend` and
+                                                          :zeek:see:`Storage::Sync::open_backend`.
+:zeek:type:`Storage::PutArgs`: :zeek:type:`record`        Record for passing arguments to :zeek:see:`Storage::Async::put` and
+                                                          :zeek:see:`Storage::Sync::put`.
+:zeek:type:`Storage::Backend`: :zeek:type:`enum`          
+:zeek:type:`Storage::Serializer`: :zeek:type:`enum`       
+========================================================= ===================================================================
+
+
+Detailed Interface
+~~~~~~~~~~~~~~~~~~
+Redefinable Options
+###################
+.. zeek:id:: Storage::default_forced_sync
+   :source-code: base/frameworks/storage/main.zeek 7 7
+
+   :Type: :zeek:type:`bool`
+   :Attributes: :zeek:attr:`&redef`
+   :Default: ``F``
+
+
+.. zeek:id:: Storage::latency_metric_bounds
+   :source-code: base/frameworks/storage/main.zeek 42 42
+
+   :Type: :zeek:type:`vector` of :zeek:type:`double`
+   :Attributes: :zeek:attr:`&redef`
+   :Default:
+
+      ::
+
+         [0.001, 0.01, 0.1, 1.0]
+
+
+
+Types
+#####
+.. zeek:type:: Storage::BackendOptions
+   :source-code: base/frameworks/storage/main.zeek 13 21
+
+   :Type: :zeek:type:`record`
+
+
+   .. zeek:field:: serializer :zeek:type:`Storage::Serializer` :zeek:attr:`&default` = ``Storage::STORAGE_SERIALIZER_JSON`` :zeek:attr:`&optional`
+
+      The serializer used for converting Zeek data.
+
+
+   .. zeek:field:: forced_sync :zeek:type:`bool` :zeek:attr:`&default` = :zeek:see:`Storage::default_forced_sync` :zeek:attr:`&optional`
+
+      Sets the backend into forced-synchronous mode. All operations will run
+      in synchronous mode, even if the async functions are called.  This
+      should generally only be set to ``T`` during testing.
+
+
+   .. zeek:field:: redis :zeek:type:`Storage::Backend::Redis::Options` :zeek:attr:`&optional`
+
+      (present if :doc:`/scripts/policy/frameworks/storage/backend/redis/main.zeek` is loaded)
+
+
+   .. zeek:field:: sqlite :zeek:type:`Storage::Backend::SQLite::Options` :zeek:attr:`&optional`
+
+      (present if :doc:`/scripts/policy/frameworks/storage/backend/sqlite/main.zeek` is loaded)
+
+
+   Base record for backend options that can be passed to
+   :zeek:see:`Storage::Async::open_backend` and
+   :zeek:see:`Storage::Sync::open_backend`. Backend plugins can redef this record
+   to add relevant fields to it.
+
+.. zeek:type:: Storage::PutArgs
+   :source-code: base/frameworks/storage/main.zeek 25 39
+
+   :Type: :zeek:type:`record`
+
+
+   .. zeek:field:: key :zeek:type:`any`
+
+      The key to store the value under.
+
+
+   .. zeek:field:: value :zeek:type:`any`
+
+      The value to store associated with the key.
+
+
+   .. zeek:field:: overwrite :zeek:type:`bool` :zeek:attr:`&default` = ``T`` :zeek:attr:`&optional`
+
+      Indicates whether this value should overwrite an existing entry for the
+      key.
+
+
+   .. zeek:field:: expire_time :zeek:type:`interval` :zeek:attr:`&default` = ``0 secs`` :zeek:attr:`&optional`
+
+      An interval of time until the entry is automatically removed from the
+      backend.
+
+
+   Record for passing arguments to :zeek:see:`Storage::Async::put` and
+   :zeek:see:`Storage::Sync::put`.
+
+.. zeek:type:: Storage::Backend
+
+   :Type: :zeek:type:`enum`
+
+      .. zeek:enum:: Storage::STORAGE_BACKEND_REDIS Storage::Backend
+
+      .. zeek:enum:: Storage::STORAGE_BACKEND_SQLITE Storage::Backend
+
+
+.. zeek:type:: Storage::Serializer
+
+   :Type: :zeek:type:`enum`
+
+      .. zeek:enum:: Storage::STORAGE_SERIALIZER_JSON Storage::Serializer
+
+
+

doc/scripts/base/frameworks/storage/sync.zeek.rst

@@ -0,0 +1,126 @@
+:tocdepth: 3
+
+base/frameworks/storage/sync.zeek
+=================================
+.. zeek:namespace:: Storage::Sync
+
+Synchronous operation methods for the storage framework.
+
+:Namespace: Storage::Sync
+:Imports: :doc:`base/frameworks/storage/main.zeek </scripts/base/frameworks/storage/main.zeek>`
+
+Summary
+~~~~~~~
+Functions
+#########
+============================================================== ===============================================================
+:zeek:id:`Storage::Sync::close_backend`: :zeek:type:`function` Closes an existing backend connection.
+:zeek:id:`Storage::Sync::erase`: :zeek:type:`function`         Erases an entry from the backend.
+:zeek:id:`Storage::Sync::get`: :zeek:type:`function`           Gets an entry from the backend.
+:zeek:id:`Storage::Sync::open_backend`: :zeek:type:`function`  Opens a new backend connection based on a configuration object.
+:zeek:id:`Storage::Sync::put`: :zeek:type:`function`           Inserts a new entry into a backend.
+============================================================== ===============================================================
+
+
+Detailed Interface
+~~~~~~~~~~~~~~~~~~
+Functions
+#########
+.. zeek:id:: Storage::Sync::close_backend
+   :source-code: base/frameworks/storage/sync.zeek 82 85
+
+   :Type: :zeek:type:`function` (backend: :zeek:type:`opaque` of Storage::BackendHandle) : :zeek:type:`Storage::OperationResult`
+
+   Closes an existing backend connection.
+   
+
+   :param backend: A handle to a backend connection.
+   
+
+   :returns: A record containing the status of the operation and an optional error
+            string for failures.
+
+.. zeek:id:: Storage::Sync::erase
+   :source-code: base/frameworks/storage/sync.zeek 101 104
+
+   :Type: :zeek:type:`function` (backend: :zeek:type:`opaque` of Storage::BackendHandle, key: :zeek:type:`any`) : :zeek:type:`Storage::OperationResult`
+
+   Erases an entry from the backend.
+   
+
+   :param backend: A handle to a backend connection.
+   
+
+   :param key: The key to erase.
+   
+
+   :returns: A record containing the status of the operation and an optional error
+            string for failures.
+
+.. zeek:id:: Storage::Sync::get
+   :source-code: base/frameworks/storage/sync.zeek 95 98
+
+   :Type: :zeek:type:`function` (backend: :zeek:type:`opaque` of Storage::BackendHandle, key: :zeek:type:`any`) : :zeek:type:`Storage::OperationResult`
+
+   Gets an entry from the backend.
+   
+
+   :param backend: A handle to a backend connection.
+   
+
+   :param key: The key to look up.
+   
+
+   :returns: A record containing the status of the operation, an optional error
+            string for failures, and an optional value for success. The value
+            returned here will be of the type passed into
+            :zeek:see:`Storage::Sync::open_backend`.
+
+.. zeek:id:: Storage::Sync::open_backend
+   :source-code: base/frameworks/storage/sync.zeek 76 79
+
+   :Type: :zeek:type:`function` (btype: :zeek:type:`Storage::Backend`, options: :zeek:type:`Storage::BackendOptions`, key_type: :zeek:type:`any`, val_type: :zeek:type:`any`) : :zeek:type:`Storage::OperationResult`
+
+   Opens a new backend connection based on a configuration object.
+   
+
+   :param btype: A tag indicating what type of backend should be opened. These are
+          defined by the backend plugins loaded.
+   
+
+   :param options: A record containing the configuration for the connection.
+   
+
+   :param key_type: The script-level type of keys stored in the backend. Used for
+             validation of keys passed to other framework methods.
+   
+
+   :param val_type: The script-level type of keys stored in the backend. Used for
+             validation of values passed to :zeek:see:`Storage::Sync::put` as well
+             as for type conversions for return values from
+             :zeek:see:`Storage::Sync::get`.
+   
+
+   :returns: A record containing the status of the operation, and either an error
+            string on failure or a value on success. The value returned here will
+            be an ``opaque of BackendHandle``.
+
+.. zeek:id:: Storage::Sync::put
+   :source-code: base/frameworks/storage/sync.zeek 88 92
+
+   :Type: :zeek:type:`function` (backend: :zeek:type:`opaque` of Storage::BackendHandle, args: :zeek:type:`Storage::PutArgs`) : :zeek:type:`Storage::OperationResult`
+
+   Inserts a new entry into a backend.
+   
+
+   :param backend: A handle to a backend connection.
+   
+
+   :param args: A :zeek:see:`Storage::PutArgs` record containing the arguments for the
+         operation.
+   
+
+   :returns: A record containing the status of the operation and an optional error
+            string for failures.
+
+