RubyGems - rbcli - Versions diffs - 0.3.3 → 0.4.0 - Mend

rbcli 0.3.3 → 0.4.0

Files changed (506) hide show

data/docs/advanced/state_storage/index.html DELETED Viewed

@@ -1,1281 +0,0 @@
-<!DOCTYPE html>
-<html lang="en" class="js csstransforms3d">
-  <head>
-    <meta charset="utf-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <meta name="generator" content="Hugo 0.125.1">
-    <meta name="description" content="">
-    <link rel="icon" href="/rbcli/images/favicon.png" type="image/png">
-    <title>State Storage :: RBCli Documentation</title>
-    <link href="/rbcli/css/nucleus.css?1713907739" rel="stylesheet">
-    <link href="/rbcli/css/fontawesome-all.min.css?1713907739" rel="stylesheet">
-    <link href="/rbcli/css/hybrid.css?1713907739" rel="stylesheet">
-    <link href="/rbcli/css/featherlight.min.css?1713907739" rel="stylesheet">
-    <link href="/rbcli/css/perfect-scrollbar.min.css?1713907739" rel="stylesheet">
-    <link href="/rbcli/css/auto-complete.css?1713907739" rel="stylesheet">
-    <link href="/rbcli/css/atom-one-dark-reasonable.css?1713907739" rel="stylesheet">
-    <link href="/rbcli/css/theme.css?1713907739" rel="stylesheet">
-    <link href="/rbcli/css/hugo-theme.css?1713907739" rel="stylesheet">
-    <link href="/rbcli/css/theme-blue.css?1713907739" rel="stylesheet">
-    <script src="/rbcli/js/jquery-3.3.1.min.js?1713907739"></script>
-    <style>
-      :root #header + #content > #left > #rlblock_left{
-          display:none !important;
-      }
-    </style>
-  </head>
-  <body class="" data-url="/rbcli/advanced/state_storage/">
-    <nav id="sidebar" class="">
-  <div id="header-wrapper">
-    <div id="header">
-      <a id="logo" href="https://akhoury6.github.io/rbcli/" style="font-size: 40px">
-  <span class="fas fa-terminal"></span>&nbsp;𝚁𝙱𝙲𝚕𝚒
-</a>
-    </div>
-        <div class="searchbox">
-    <label for="search-by"><i class="fas fa-search"></i></label>
-    <input data-search-input id="search-by" type="search" placeholder="Search...">
-    <span data-search-clear=""><i class="fas fa-times"></i></span>
-</div>
-<script type="text/javascript" src="/rbcli/js/lunr.min.js?1713907739"></script>
-<script type="text/javascript" src="/rbcli/js/auto-complete.js?1713907739"></script>
-<script type="text/javascript">
-        var baseurl = "https:\/\/akhoury6.github.io\/rbcli\/";
-</script>
-<script type="text/javascript" src="/rbcli/js/search.js?1713907739"></script>
-  </div>
-    <div class="highlightable">
-    <ul class="topics">
-    <li data-nav-id="/rbcli/quick_reference/" title="Quick Reference" class="dd-item
-        ">
-      <a href="/rbcli/quick_reference/">
-          Quick Reference
-      </a>
-    </li>
-    <li data-nav-id="/rbcli/tutorial/" title="Tutorial" class="dd-item
-        ">
-      <a href="/rbcli/tutorial/">
-          Tutorial
-      </a>
-        <ul>
-      <li data-nav-id="/rbcli/tutorial/10-getting_started/" title="Getting Started" class="dd-item ">
-        <a href="/rbcli/tutorial/10-getting_started/">
-        <b>1. </b>Getting Started
-        </a>
-    </li>
-      <li data-nav-id="/rbcli/tutorial/20-project_layout/" title="The Project Layout" class="dd-item ">
-        <a href="/rbcli/tutorial/20-project_layout/">
-        <b>2. </b>The Project Layout
-        </a>
-    </li>
-      <li data-nav-id="/rbcli/tutorial/30-your_first_command/" title="Your First Command" class="dd-item ">
-        <a href="/rbcli/tutorial/30-your_first_command/">
-        <b>3. </b>Your First Command
-        </a>
-    </li>
-      <li data-nav-id="/rbcli/tutorial/40-options_parameters_and_arguments/" title="Options, Parameters, and Arguments" class="dd-item ">
-        <a href="/rbcli/tutorial/40-options_parameters_and_arguments/">
-        <b>4. </b>Options, Parameters, and Arguments
-        </a>
-    </li>
-      <li data-nav-id="/rbcli/tutorial/50-publishing/" title="Publishing Your Application" class="dd-item ">
-        <a href="/rbcli/tutorial/50-publishing/">
-        <b>5. </b>Publishing Your Application
-        </a>
-    </li>
-        </ul>
-    </li>
-    <li data-nav-id="/rbcli/advanced/" title="Advanced" class="dd-item
-        parent
-        ">
-      <a href="/rbcli/advanced/">
-          Advanced
-      </a>
-        <ul>
-      <li data-nav-id="/rbcli/advanced/automatic_updates/" title="Automatic Updates" class="dd-item ">
-        <a href="/rbcli/advanced/automatic_updates/">
-        Automatic Updates
-        </a>
-    </li>
-      <li data-nav-id="/rbcli/advanced/command_types/" title="Command Types" class="dd-item ">
-        <a href="/rbcli/advanced/command_types/">
-        Command Types
-        </a>
-    </li>
-      <li data-nav-id="/rbcli/advanced/distributed_state_locking/" title="Distributed State and Locking" class="dd-item ">
-        <a href="/rbcli/advanced/distributed_state_locking/">
-        Distributed State and Locking
-        </a>
-    </li>
-      <li data-nav-id="/rbcli/advanced/hooks/" title="Execution Hooks" class="dd-item ">
-        <a href="/rbcli/advanced/hooks/">
-        Execution Hooks
-        </a>
-    </li>
-      <li data-nav-id="/rbcli/advanced/interactive_commands/" title="Interactive Commands" class="dd-item ">
-        <a href="/rbcli/advanced/interactive_commands/">
-        Interactive Commands
-        </a>
-    </li>
-      <li data-nav-id="/rbcli/advanced/logging/" title="Logging" class="dd-item ">
-        <a href="/rbcli/advanced/logging/">
-        Logging
-        </a>
-    </li>
-      <li data-nav-id="/rbcli/advanced/remote_execution/" title="Remote Execution" class="dd-item ">
-        <a href="/rbcli/advanced/remote_execution/">
-        Remote Execution
-        </a>
-    </li>
-      <li data-nav-id="/rbcli/advanced/state_storage/" title="State Storage" class="dd-item active">
-        <a href="/rbcli/advanced/state_storage/">
-        State Storage
-        </a>
-    </li>
-      <li data-nav-id="/rbcli/advanced/user_config_files/" title="User Configuration Files" class="dd-item ">
-        <a href="/rbcli/advanced/user_config_files/">
-        User Configuration Files
-        </a>
-    </li>
-        </ul>
-    </li>
-    <li data-nav-id="/rbcli/development/" title="Development" class="dd-item
-        ">
-      <a href="/rbcli/development/">
-          Development
-      </a>
-        <ul>
-      <li data-nav-id="/rbcli/development/contributing/" title="Contribution Guide" class="dd-item ">
-        <a href="/rbcli/development/contributing/">
-        Contribution Guide
-        </a>
-    </li>
-      <li data-nav-id="/rbcli/development/license/" title="License Info" class="dd-item ">
-        <a href="/rbcli/development/license/">
-        License Info
-        </a>
-    </li>
-      <li data-nav-id="/rbcli/development/code_of_conduct/" title="Code of Conduct" class="dd-item ">
-        <a href="/rbcli/development/code_of_conduct/">
-        Code of Conduct
-        </a>
-    </li>
-      <li data-nav-id="/rbcli/development/changelog/" title="Changelog" class="dd-item ">
-        <a href="/rbcli/development/changelog/">
-        Changelog
-        </a>
-    </li>
-        </ul>
-    </li>
-    <li data-nav-id="/rbcli/whoami/" title="My Letter To You" class="dd-item
-        ">
-      <a href="/rbcli/whoami/">
-          My Letter To You
-      </a>
-    </li>
-    </ul>
-      <section id="shortcuts">
-        <h3>More</h3>
-        <ul>
-              <li>
-                  <a class="padding" href="https://github.com/akhoury6/rbcli"><i class='fab fa-github'></i> Github repo</a>
-              </li>
-              <li>
-                  <a class="padding" href="https://rubygems.org/gems/rbcli"><i class='far fa-gem'></i> Rubygems</a>
-              </li>
-        </ul>
-      </section>
-    <section id="footer">
-      <p>Built with <a href="https://github.com/matcornic/hugo-theme-learn"><i class="fas fa-heart"></i></a> from <a href="https://getgrav.org">Grav</a> and <a href="https://gohugo.io/">Hugo</a></p>
-    </section>
-  </div>
-</nav>
-        <section id="body">
-        <div id="overlay"></div>
-        <div class="padding highlightable">
-              <div>
-                <div id="top-bar">
-                <div id="breadcrumbs" itemscope="" itemtype="http://data-vocabulary.org/Breadcrumb">
-                    <span id="sidebar-toggle-span">
-                        <a href="#" id="sidebar-toggle" data-sidebar-toggle="">
-                          <i class="fas fa-bars"></i>
-                        </a>
-                    </span>
-                  <span id="toc-menu"><i class="fas fa-list-alt"></i></span>
-                  <span class="links">
-            <a href='/rbcli/'></a> > <a href='/rbcli/advanced/'>Advanced</a> > State Storage
-                  </span>
-                </div>
-                    <div class="progress">
-    <div class="wrapper">
-<nav id="TableOfContents">
-  <ul>
-    <li><a href="#local-state">Local State</a>
-      <ul>
-        <li><a href="#configuration">Configuration</a></li>
-        <li><a href="#access-and-usage">Access and Usage</a></li>
-      </ul>
-    </li>
-    <li><a href="#remote-state">Remote State</a>
-      <ul>
-        <li><a href="#configuration-1">Configuration</a></li>
-        <li><a href="#access-and-usage-1">Access and Usage</a></li>
-      </ul>
-    </li>
-  </ul>
-</nav>
-    </div>
-</div>
-              </div>
-            </div>
-        <div id="head-tags">
-        </div>
-        <div id="body-inner">
-            <h1>
-              State Storage
-            </h1>
-<p>RBCli supports both local and remote state storage. This is done by synchronizing a Hash with either the local disk or a remote database.</p>
-<h2 id="local-state">Local State</h2>
-<p>RBCli&rsquo;s local state storage gives you access to a hash that is automatically persisted to disk when changes are made.</p>
-<h3 id="configuration">Configuration</h3>
-<p>You can configure it in <code>config/storage.rb</code>.</p>
-<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-ruby" data-lang="ruby"><span style="display:flex;"><span>local_state <span style="color:#e6db74">&#39;/var/mytool/localstate&#39;</span>, <span style="color:#e6db74">force_creation</span>: <span style="color:#66d9ef">true</span>, <span style="color:#e6db74">halt_on_error</span>: <span style="color:#66d9ef">true</span>
-</span></span></code></pre></div><p>There are three parameters to configure it with:</p>
-<ul>
-<li>The <code>path</code> as a string (self-explanatory)</li>
-<li><code>force_creation</code>
-<ul>
-<li>This will attempt to create the path and file if it does not exist (equivalent to an <code>mkdir -p</code> and <code>touch</code> in linux)</li>
-</ul>
-</li>
-<li><code>halt_on_error</code>
-<ul>
-<li>RBCli&rsquo;s default behavior is to raise an exception if the file can not be created, read, or updated at any point in time</li>
-<li>If this is set to <code>false</code>, RBCli will silence any errors pertaining to file access and will fall back to whatever data is available. Note that if this is enabled, changes made to the state may not be persisted to disk.
-<ul>
-<li>If creation fails and file does not exist, you start with an empty hash</li>
-<li>If file exists but can&rsquo;t be read, you will have an empty hash</li>
-<li>If file can be read but not written, the hash will be populated with the data. Writes will be stored in memory while the application is running, but will not be persisted to disk.</li>
-</ul>
-</li>
-</ul>
-</li>
-</ul>
-<h3 id="access-and-usage">Access and Usage</h3>
-<p>Once configured you can access it with a standard hash syntax in your Standard Commands:</p>
-<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-ruby" data-lang="ruby"><span style="display:flex;"><span><span style="color:#66d9ef">Rbcli</span><span style="color:#f92672">.</span>local_state<span style="color:#f92672">[</span><span style="color:#e6db74">:yourkeyhere</span><span style="color:#f92672">]</span>
-</span></span></code></pre></div><p>The methods available for use at the top level are as follows:</p>
-<p>Hash native methods:</p>
-<ul>
-<li><code>[]</code> (Regular hash syntax. Keys are accessed via either symbols or strings indifferently.)</li>
-<li><code>[]=</code> (Assignment operator)</li>
-<li><code>delete</code></li>
-<li><code>each</code></li>
-<li><code>key?</code></li>
-</ul>
-<p>Additional methods:</p>
-<ul>
-<li><code>commit</code>
-<ul>
-<li>Every assignment to the top level of the hash will result in a write to disk (for example: <code>Rbcli.local_state[:yourkey] = 'foo'</code>). However, if you are manipulating nested hashes, these saves will not be triggered. You can trigger them manually by calling <code>commit</code>.</li>
-</ul>
-</li>
-<li><code>clear</code>
-<ul>
-<li>Resets the data back to an empty hash.</li>
-</ul>
-</li>
-<li><code>refresh</code>
-<ul>
-<li>Loads the most current version of the data from the disk</li>
-</ul>
-</li>
-<li><code>disconnect</code>
-<ul>
-<li>Removes the data from memory and sets <code>Rbcli.local_state = nil</code>. Data will be read from disk again on next access.</li>
-</ul>
-</li>
-</ul>
-<p>Every assignment will result in a write to disk, so if an operation will require a large number of assignments/writes it should be performed to a different hash before beign assigned to this one.</p>
-<h2 id="remote-state">Remote State</h2>
-<p>RBCli&rsquo;s remote state storage gives you access to a hash that is automatically persisted to a remote storage location when changes are made. It has optional locking built-in, meaning that multiple users may share remote state without any data consistency issues.</p>
-<p>Currently, this feature requires AWS DynamoDB, though other backend systems will be added in the future.</p>
-<h3 id="configuration-1">Configuration</h3>
-<p>Before DynamoDB can be used, AWS API credentials have to be created and made available. RBCli will attempt to find credentials from the following locations in order:</p>
-<ol>
-<li>User&rsquo;s config file</li>
-<li>Environment variables <code>AWS_ACCESS_KEY_ID</code> and <code>AWS_SECRET_ACCESS_KEY</code></li>
-<li>User&rsquo;s AWSCLI configuration at <code>~/.aws/credentials</code></li>
-</ol>
-<p>For more information about generating and storing AWS credentials, see <a href="https://docs.aws.amazon.com/sdk-for-ruby/v3/developer-guide/setup-config.html">Configuring the AWS SDK for Ruby</a>. Please make sure that your users are aware that they will need to provide their own credentials to use this feature.</p>
-<p>You can configure it in <code>config/storage.rb</code>.</p>
-<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-ruby" data-lang="ruby"><span style="display:flex;"><span>remote_state_dynamodb <span style="color:#e6db74">table_name</span>: <span style="color:#e6db74">&#39;mytable&#39;</span>, <span style="color:#e6db74">region</span>: <span style="color:#e6db74">&#39;us-east-1&#39;</span>, <span style="color:#e6db74">force_creation</span>: <span style="color:#66d9ef">true</span>, <span style="color:#e6db74">halt_on_error</span>: <span style="color:#66d9ef">true</span>, <span style="color:#e6db74">locking</span>: <span style="color:#66d9ef">false</span>
-</span></span></code></pre></div><p>These are the parameters:</p>
-<ul>
-<li><code>table_name</code>
-<ul>
-<li>The name of the DynamoDB table to use.</li>
-</ul>
-</li>
-<li><code>region</code>
-<ul>
-<li>The AWS region that the database is located</li>
-</ul>
-</li>
-<li><code>force_creation</code>
-<ul>
-<li>Creates the DynamoDB table if it does not already exist</li>
-</ul>
-</li>
-<li><code>halt_on_error</code>
-<ul>
-<li>Similar to the way <a href="#local-state">Local State</a> works, setting this to <code>false</code> will silence any errors in connecting to the DynamoDB table. Instead, your application will simply have access to an empty hash that does not get persisted anywhere.</li>
-<li>This is good for use cases that involve using this storage as a cache, where a connection error might mean the feature doesn&rsquo;t work but its not important enough to interrupt the user.</li>
-</ul>
-</li>
-<li><code>locking</code>
-<ul>
-<li>Setting this to <code>true</code> enables locking, meaning only one instance of your application can access the shared data at any given time. For more information see <a href="/rbcli/advanced/distributed_state_locking/">Distributed State Locking</a>.</li>
-</ul>
-</li>
-</ul>
-<h3 id="access-and-usage-1">Access and Usage</h3>
-<p>Once configured you can access it with a standard hash syntax:</p>
-<div class="highlight"><pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;"><code class="language-ruby" data-lang="ruby"><span style="display:flex;"><span><span style="color:#66d9ef">Rbcli</span><span style="color:#f92672">.</span>remote_state<span style="color:#f92672">[</span><span style="color:#e6db74">:yourkeyhere</span><span style="color:#f92672">]</span>
-</span></span></code></pre></div><p>This works the same way that <a href="#local-state">Local State</a> does, with the same performance caveats (try not to write too frequently).</p>
-<p>Note that all state in Rbcli is <strong>lazy-loaded</strong>, so no connections will be made until your code attempts to access the data even if the feature is enabled.</p>
-<p>For more information on the available commands, see the documentation on <a href="#local-state">Local State</a></p>
-<footer class="footline">
-</footer>
-        </div>
-      </div>
-    <div id="navigation">
-			<a class="nav nav-prev" href="/rbcli/advanced/remote_execution/" title="Remote Execution"> <i class="fa fa-chevron-left"></i></a>
-			<a class="nav nav-next" href="/rbcli/advanced/user_config_files/" title="User Configuration Files" style="margin-right: 0px;"><i class="fa fa-chevron-right"></i></a>
-    </div>
-    </section>
-    <div style="left: -1000px; overflow: scroll; position: absolute; top: -1000px; border: none; box-sizing: content-box; height: 200px; margin: 0px; padding: 0px; width: 200px;">
-      <div style="border: none; box-sizing: content-box; height: 200px; margin: 0px; padding: 0px; width: 200px;"></div>
-    </div>
-    <script src="/rbcli/js/clipboard.min.js?1713907739"></script>
-    <script src="/rbcli/js/perfect-scrollbar.min.js?1713907739"></script>
-    <script src="/rbcli/js/perfect-scrollbar.jquery.min.js?1713907739"></script>
-    <script src="/rbcli/js/jquery.sticky.js?1713907739"></script>
-    <script src="/rbcli/js/featherlight.min.js?1713907739"></script>
-    <script src="/rbcli/js/highlight.pack.js?1713907739"></script>
-    <script>hljs.initHighlightingOnLoad();</script>
-    <script src="/rbcli/js/modernizr.custom-3.6.0.js?1713907739"></script>
-    <script src="/rbcli/js/learn.js?1713907739"></script>
-    <script src="/rbcli/js/hugo-learn.js?1713907739"></script>
-    <link href="/rbcli/mermaid/mermaid.css?1713907739" rel="stylesheet" />
-    <script src="/rbcli/mermaid/mermaid.js?1713907739"></script>
-    <script>
-        mermaid.initialize({ startOnLoad: true });
-    </script>
-  </body>
-</html>