Circle #325

Author: yogthos

docs/docs/clojurescript.html

@@ -112,7 +112,7 @@ <h2>Contents</h2>
     &#91;:input {:type &quot;text&quot;
              :value @state
              :on-change #&#40;reset! state &#40;-&gt; % .-target .-value&#41;&#41;}&#93;&#93;&#41;
-</code></pre><p>Above, the <code>input-field</code> component consists of a <code>label</code> component we defined earlier and an <code>:input</code> component. The input will update the <code>state</code> atom and render it as its value.</p><p>Notice that even though <code>label</code> is a function we're not calling it, but instead we're putting it in a vector. The reason for this is that we're specifying the component hierarchy. The components will be run by Reagent when they need to be rendered.</p><p>This is behavior makes it trivial to implement the <a href='http://facebook.github.io/react/docs/flux-overview.html'>React Flux</a> pattern.</p><pre><code>Views---&gt;&#40;actions&#41; --&gt; Dispatcher--&gt;&#40;callback&#41;--&gt; Stores---+
+</code></pre><p>Above, the <code>input-field</code> component consists of a <code>label</code> component we defined earlier and an <code>:input</code> component. The input will update the <code>state</code> atom and render it as its value.</p><p>Notice that even though <code>label</code> is a function we're not calling it, but instead we're putting it in a vector. The reason for this is that we're specifying the component hierarchy. The components will be run by Reagent when they need to be rendered.</p><p>This is behavior makes it trivial to implement the <a href='https://facebookarchive.github.io/flux/docs/in-depth-overview'>React Flux</a> pattern.</p><pre><code>Views---&gt;&#40;actions&#41; --&gt; Dispatcher--&gt;&#40;callback&#41;--&gt; Stores---+
 Ʌ                                                          |
 |                                                          V
 +--&#40;event handlers update&#41;--&#40;Stores emit &quot;change&quot; events&#41;--+
@@ -201,10 +201,9 @@ <h2>Contents</h2>
    &#91;&quot;/send-message&quot; {:post save-message!}&#93;&#93;&#41;
 </code></pre><p>Note that CSRF middleware is enabled by default. The middleware wraps the <code>home-routes</code> of your application. It will intercept any request to the server that isn't a <code>HEAD</code> or <code>GET</code>.</p><pre><code class="clojure">&#40;defn home-routes &#91;base-path&#93;
   &#91;base-path
-   {:middleware &#91;middleware/wrap-csrf
-                 middleware/wrap-formats&#93;}
+   {:middleware &#91;middleware/wrap-formats&#93;}
    &#91;&quot;/&quot; {:get home-page}&#93;&#93;&#41;
-</code></pre><p>We would now need to pass the CSRF token along with the request. One way to do this is to pass the token in the <code>x-csrf-token</code> header in the request with the value of the token.</p><p>To do that we'll first need to set the token as a hidden field on the page:</p><pre><code class="xml">&lt;input id=&quot;csrf-token&quot; type=&quot;hidden&quot; value=&quot;{{csrf-token}}&quot;&gt;&lt;/input&gt;
+</code></pre><p>Note that CSRF protection is configured via <code>:anti-forgery</code> in the site defaults configuration in <code>system.edn</code>, and is applied globally by <code>ring-defaults</code> rather than as a per-route middleware.</p><p>We would now need to pass the CSRF token along with the request. One way to do this is to pass the token in the <code>x-csrf-token</code> header in the request with the value of the token.</p><p>To do that we'll first need to set the token as a hidden field on the page:</p><pre><code class="xml">&lt;input id=&quot;csrf-token&quot; type=&quot;hidden&quot; value=&quot;{{csrf-token}}&quot;&gt;&lt;/input&gt;
 </code></pre><p>Then we'll have to set the header in the request:</p><pre><code class="clojure">&#40;POST &quot;/send-message&quot;
         {:headers {&quot;Accept&quot; &quot;application/transit+json&quot;
                    &quot;x-csrf-token&quot; &#40;.-value &#40;.getElementById js/document &quot;csrf-token&quot;&#41;&#41;}

docs/docs/guestbook.html

@@ -66,8 +66,8 @@ <h2 id="guestbook&#95;application">Guestbook Application</h2><p>This tutorial wi
 </code></pre><p>Linux</p><pre><code>curl -L -O https://github.com/clojure/brew-install/releases/latest/download/posix-install.sh
 chmod +x posix-install.sh
 sudo ./posix-install.sh
-</code></pre><p>For both macOS and Linux, you will need <a href='https://github.com/seancorfield/clj-new'><code>clj-new</code></a> installed as follows:</p><pre><code>clojure -Ttools install com.github.seancorfield/clj-new '{:git/tag &quot;v1.2.404&quot;}' :as clj-new
-</code></pre><p>For information on customization options, for example on how to change your install location, see <a href='https://clojure.org/guides/getting_started#_clojure_installer_and_cli_tools'>the official docs here</a>.</p><h3 id="creating&#95;a&#95;new&#95;application">Creating a new application</h3><p>Once you have the Clojure CLI installed, you can run the following commands in your terminal to initialize your application:</p><pre><code>clojure -Tclj-new create :template io.github.kit-clj :name kit/guestbook
+</code></pre><p>For both macOS and Linux, you will also need <a href='https://github.com/babashka/neil'>neil</a> to generate new projects:</p><pre><code>brew install babashka/brew/neil
+</code></pre><p>Alternatively, you can use <a href='https://github.com/seancorfield/deps-new'>deps-new</a> directly. For information on customization options, for example on how to change your install location, see <a href='https://clojure.org/guides/getting_started#_clojure_installer_and_cli_tools'>the official docs here</a>.</p><h3 id="creating&#95;a&#95;new&#95;application">Creating a new application</h3><p>Once you have the Clojure CLI installed, you can run the following commands in your terminal to initialize your application:</p><pre><code>neil new io.github.kit-clj/kit kit/guestbook
 cd guestbook
 </code></pre><p>The above will create a new project, named kit/guestbook, based on the kit-clj template.</p><h3 id="anatomy&#95;of&#95;a&#95;kit&#95;application">Anatomy of a Kit application</h3><p>The newly created application has the following structure:</p><pre><code>├── Dockerfile
 ├── README.md

docs/docs/profiles.html

@@ -62,8 +62,8 @@ <h2>Contents</h2>
       <ol class="contents"><li><a href="#profiles">Profiles</a></li><li><a href="#libraries">Libraries</a></li></ol>
 
       <div id="content">
-        <h2 id="profiles">Profiles</h2><p>Profiles are clj-new template arguments. They are helpful when you are starting a new project and know ahead of time what functionality you will need. In such cases, you can use profiles to set up a new Kit project without having to manually add libraries and wire them together.</p><p>Unlike <a href='/docs/modules.html'>modules</a>, profiles are tied to clj-new, the project generation tool. You can only use them when creating a project.</p><p>Running <code>clojure -Tclj-new create :template io.github.kit-clj :name yourname/app</code> will create an application using the default profile template. However, if you would like to attach further functionality to your template you can append profile hints for the extended functionality.</p><p>Default libs included with no profile specified:</p><ul><li><code>kit-core</code></li><li><code>kit-undertow</code></li></ul><p>Additional profiles:</p><ul><li><code>+xtdb</code> - Adds the <code>kit-xtdb</code> lib</li><li><code>+hato</code> - Adds the <code>kit-hato</code> lib</li><li><code>+metrics</code> - Adds the <code>kit-metrics</code> lib</li><li><code>+nrepl</code> - Adds the <code>kit-nrepl</code> lib, removes the <code>kit-repl</code> lib. Note that you do not need this profile to use nREPL during development.</li><li><code>+quartz</code> - Adds the <code>kit-quartz</code> lib</li><li><code>+redis</code> - Adds the <code>kit-redis</code> lib</li><li><code>+selmer</code> - Adds the <code>kit-selmer</code> lib</li><li><code>+socket-repl</code> - Adds the <code>kit-repl</code> lib</li><li><code>+sql</code> - Adds the <code>kit-sql</code> and <code>kit-postgres</code> libs</li><li><code>+full</code> - Adds the libs <code>kit-xtdb</code>, <code>kit-hato</code>, <code>kit-metrics</code>, <code>kit-quartz</code>, <code>kit-redis</code>, <code>kit-repl</code>, <code>kit-selmer</code>, and <code>kit-sql</code></li></ul><p>To add a profile, pass it as an argument after your application name, e.g.:</p><pre><code>clojure -Tclj-new create :template io.github.kit-clj :name yourname/app :args '&#91;+selmer&#93;'
-</code></pre><p>You can also mix multiple profiles when creating the application, e.g.:</p><pre><code>clojure -Tclj-new create :template io.github.kit-clj :name yourname/app :args '&#91;+selmer +xtdb&#93;'
+        <h2 id="profiles">Profiles</h2><p>Profiles are template arguments used when generating a new project. They are helpful when you are starting a new project and know ahead of time what functionality you will need. In such cases, you can use profiles to set up a new Kit project without having to manually add libraries and wire them together.</p><p>Unlike <a href='/docs/modules.html'>modules</a>, profiles are tied to the project generation tool. You can only use them when creating a project.</p><p>Running <code>neil new io.github.kit-clj/kit yourname/app</code> will create an application using the default profile template. However, if you would like to attach further functionality to your template you can append profile hints for the extended functionality.</p><p>Default libs included with no profile specified:</p><ul><li><code>kit-core</code></li><li><code>kit-undertow</code></li></ul><p>Additional profiles:</p><ul><li><code>+xtdb</code> - Adds the <code>kit-xtdb</code> lib</li><li><code>+hato</code> - Adds the <code>kit-hato</code> lib</li><li><code>+metrics</code> - Adds the <code>kit-metrics</code> lib</li><li><code>+nrepl</code> - Adds the <code>kit-nrepl</code> lib, removes the <code>kit-repl</code> lib. Note that you do not need this profile to use nREPL during development.</li><li><code>+quartz</code> - Adds the <code>kit-quartz</code> lib</li><li><code>+redis</code> - Adds the <code>kit-redis</code> lib</li><li><code>+selmer</code> - Adds the <code>kit-selmer</code> lib</li><li><code>+socket-repl</code> - Adds the <code>kit-repl</code> lib</li><li><code>+sql</code> - Adds the <code>kit-sql</code> and <code>kit-postgres</code> libs</li><li><code>+full</code> - Adds the libs <code>kit-xtdb</code>, <code>kit-hato</code>, <code>kit-metrics</code>, <code>kit-quartz</code>, <code>kit-redis</code>, <code>kit-repl</code>, <code>kit-selmer</code>, and <code>kit-sql</code></li></ul><p>To add a profile, pass it as an argument after your application name, e.g.:</p><pre><code>neil new io.github.kit-clj/kit yourname/app --selmer
+</code></pre><p>You can also mix multiple profiles when creating the application, e.g.:</p><pre><code>neil new io.github.kit-clj/kit yourname/app --selmer --xtdb
 </code></pre><h3 id="libraries">Libraries</h3><ul><li><code>kit-core</code> - Basic utility functions used by some other libs</li><li><code>kit-xtdb</code> - Simple binding to connect to a <a href='https://xtdb.com/'>XTDB</a> database node</li><li><code>kit-hato</code> - HTTP client using <a href='https://github.com/gnarroway/hato'>hato</a></li><li><code>kit-metrics</code> - Configurable metrics using <a href='https://github.com/clj-commons/iapetos'>iapetos</a></li><li><code>kit-nrepl</code> - <a href='https://github.com/nrepl/nrepl'>nREPL</a> component. Note that you do not need this library to use nREPL during development.</li><li><code>kit-quartz</code> - Scheduler using <a href='https://github.com/troy-west/cronut'>cronut</a> as an integrant binding for <a href='http://www.quartz-scheduler.org/'>quartz</a>. Exposes the <code>cronut</code> API, simply some extensions for <code>aero</code> and utilities</li><li><code>kit-redis</code> - Extension of <a href='https://github.com/clojure/core.cache'>core.cache</a> for Redis via <a href='https://github.com/ptaoussanis/carmine'>carmine</a></li><li><code>kit-repl</code> - Socket REPL integrant binding</li><li><code>kit-selmer</code> - Templating configuration with <a href='https://github.com/yogthos/Selmer'>selmer</a></li><li><code>kit-sql</code> - Generic SQL integrant binding. Uses <a href='https://github.com/luminus-framework/conman'>conman</a>, <a href='https://github.com/seancorfield/next-jdbc'>next.jdbc</a>, <a href='https://www.hugsql.org/'>hugsql</a>, and <a href='https://github.com/yogthos/migratus'>migratus</a> directly, or implicitly. By default, imports <code>kit-postgres</code> lib which supports Postgresql</li><li><code>kit-postgres</code> - Lib with data bindings and utilities for working with Postgres</li><li><code>kit-undertow</code> - Server binding via <a href='https://github.com/luminus-framework/luminus-undertow'>luminus-undertow</a></li></ul>
       </div>
     </div>

docs/docs/routes.html

@@ -80,11 +80,11 @@ <h2>Contents</h2>
 body params: {:password &quot;xyz&quot;, :username &quot;xyz&quot;}
 </code></pre><p>In the guestbook application example we saw the following route defined:</p><pre><code class="clojure">&#91;&quot;/&quot; {:get home-page
       :post save-message!}&#93;
-</code></pre><p>This route serves the home page when it receives a <code>GET</code> request and extracts the name and the message form parameters when it receives a <code>POST</code> request. Note that <code>POST</code> requests must contain a CSRF token by default. This is handled by the <code>middleware/wrap-csrf</code> declaration below:</p><pre><code class="clojure">&#40;defn home-routes &#91;base-path&#93;
+</code></pre><p>This route serves the home page when it receives a <code>GET</code> request and extracts the name and the message form parameters when it receives a <code>POST</code> request. Note that <code>POST</code> requests must contain a CSRF token when anti-forgery protection is enabled in your site defaults configuration.</p><pre><code class="clojure">&#40;defn home-routes &#91;base-path&#93;
   &#91;base-path
    &#91;&quot;/&quot; {:get home-page
          :post save-message!}&#93;&#93;&#41;
-</code></pre><p>Please refer <a href='/docs/security.html#cross_site_request_forgery_protection'>here</a> for more details on managing CSRF middleware.</p><h3 id="return&#95;values">Return values</h3><p>The return value of a route block determines at least the response body passed on to the HTTP client, or at least the next middleware in the ring stack. Most commonly, this is a string, as in the above examples. But, we may also return a <a href='https://github.com/ring-clojure/ring/blob/master/SPEC'>response map</a>:</p><pre><code class="clojure">&#91;&quot;/&quot; {:get &#40;fn &#91;request&#93; {:status 200 :body &quot;Hello World&quot;}&#41;}&#93;
+</code></pre><p>CSRF protection is provided by <a href='https://github.com/ring-clojure/ring-defaults'>ring-defaults</a> via the <code>:anti-forgery</code> key in your site defaults configuration in <code>system.edn</code>. When enabled, <code>ring.middleware.anti-forgery/wrap-anti-forgery</code> is applied automatically. In HTML forms, use the <code>{% csrf-field %}</code> Selmer tag to include the token.</p><h3 id="return&#95;values">Return values</h3><p>The return value of a route block determines at least the response body passed on to the HTTP client, or at least the next middleware in the ring stack. Most commonly, this is a string, as in the above examples. But, we may also return a <a href='https://github.com/ring-clojure/ring/blob/master/SPEC'>response map</a>:</p><pre><code class="clojure">&#91;&quot;/&quot; {:get &#40;fn &#91;request&#93; {:status 200 :body &quot;Hello World&quot;}&#41;}&#93;
 
 &#91;&quot;/is-403&quot; {:get &#40;fn &#91;request&#93; {:status 403 :body &quot;&quot;}&#41;}&#93;
 

docs/docs/sessions.html

@@ -86,8 +86,7 @@ <h2 id="sessions">Sessions</h2><p>Kit defaults to using cookie-based sessions.</
 
 &#40;def app-routes
   &#91;&quot;&quot;
-   {:middleware &#91;middleware/wrap-csrf
-                 middleware/wrap-formats&#93;}
+   {:middleware &#91;middleware/wrap-formats&#93;}
    &#91;&quot;/login/:id&quot; {:get &#40;fn &#91;{:keys &#91;path-params&#93; :as req}&#93;
                          &#40;set-user! &#40;:id path-params&#41; req&#41;&#41;}&#93;
    &#91;&quot;/remove&quot; {:get remove-user!}&#93;

docs/index.html

@@ -126,10 +126,10 @@ <h3>Introductory Kit Course</h3>
 </div>
 
 <div class="column-wrapper" id="easy-start">
-  <p>Using <a href="https://clojure.org/guides/getting_started">Clojure tools</a>, getting started is as easy as:</p>
+  <p>Using <a href="https://github.com/babashka/neil">neil</a> and <a href="https://clojure.org/guides/getting_started">Clojure tools</a>, getting started is as easy as:</p>
   <pre class="bash hljs">
-    <span class="prompt">$ </span><span class="cmd">clojure -Ttools install com.github.seancorfield/clj-new '{:git/tag "v1.2.404"}' :as clj-new</span>
-    <span class="prompt">$ </span><span class="cmd">clojure -Tclj-new create :template io.github.kit-clj :name yourname/guestbook</span>
+    <span class="prompt">$ </span><span class="cmd">brew install clojure/tools/clojure babashka/brew/neil</span>
+    <span class="prompt">$ </span><span class="cmd">neil new io.github.kit-clj/kit yourname/guestbook</span>
   </pre>
   <h4><a href="https://github.com/kit-clj/playground/">Quickstart with Github Codespaces</a></h4>  
 </div>