Document Request.js in the guides [ci-skip]

p8 · p8 · commit 83574a7de241 · 2023-02-13T22:19:34.000+01:00
With the removal of UJS as a default dependency, it can be unclear what
to use for Ajax calls. The Rails Request.js is the official library to
use in this case, so it should be documented in the guides.
diff --git a/guides/source/security.md b/guides/source/security.md
@@ -250,6 +250,8 @@ CSRF appears very rarely in CVE (Common Vulnerabilities and Exposures) - less th
 
 NOTE: _First, as is required by the W3C, use GET and POST appropriately. Secondly, a security token in non-GET requests will protect your application from CSRF._
 
+#### Use GET and POST Appropriately
+
 The HTTP protocol basically provides two main types of requests - GET and POST (DELETE, PUT, and PATCH should be used like POST). The World Wide Web Consortium (W3C) provides a checklist for choosing HTTP GET or POST:
 
 **Use GET if:**
@@ -287,21 +289,52 @@ There are many other possibilities, like using a `<script>` tag to make a cross-
 
 NOTE: We can't distinguish a `<script>` tag's origin—whether it's a tag on your own site or on some other malicious site—so we must block all `<script>` across the board, even if it's actually a safe same-origin script served from your own site. In these cases, explicitly skip CSRF protection on actions that serve JavaScript meant for a `<script>` tag.
 
+#### Required Security Token
+
 To protect against all other forged requests, we introduce a _required security token_ that our site knows but other sites don't know. We include the security token in requests and verify it on the server. This is done automatically when [`config.action_controller.default_protect_from_forgery`][] is set to `true`, which is the default for newly created Rails applications. You can also do it manually by adding the following to your application controller:
 
 ```ruby
 protect_from_forgery with: :exception
 ```
 
-This will include a security token in all forms and Ajax requests generated by Rails. If the security token doesn't match what was expected, an exception will be thrown.
+This will include a security token in all forms generated by Rails. If the
+security token doesn't match what was expected, an exception will be thrown.
+
+When submitting forms with [Turbo](https://turbo.hotwired.dev/) the security
+token is required as well. Turbo looks for the token in the `csrf` meta tags of
+your application layout and adds it to request in the `X-CSRF-Token` request
+header. These meta tags are created with the [`csrf_meta_tags`][] helper
+method:
+
+```erb
+<head>
+  <%= csrf_meta_tags %>
+</head>
+```
+
+which results in:
+
+```html
+<head>
+  <meta name="csrf-param" content="authenticity_token" />
+  <meta name="csrf-token" content="THE-TOKEN" />
+</head>
+```
+
+When making your own non-GET requests from JavaScript the security token is
+required as well. [Rails Request.JS](https://github.com/rails/request.js) is a
+JavaScript library that encapsulates the logic of adding the required request
+headers.
+
+When using another library to make Ajax calls, it is necessary to add the
+security token as a default header yourself. To get the token from the meta tag
+you could do something like:
+
+```javascript
+document.head.querySelector("meta[name=csrf-token]")?.content
+```
 
-NOTE: By default, Rails includes an [unobtrusive scripting adapter](https://github.com/rails/rails/blob/main/actionview/app/assets/javascripts),
-which adds a header called `X-CSRF-Token` with the security token on every non-GET
-Ajax call. Without this header, non-GET Ajax requests won't be accepted by Rails.
-When using another library to make Ajax calls, it is necessary to add the security
-token as a default header for Ajax calls in your library. To get the token, have
-a look at `<meta name='csrf-token' content='THE-TOKEN'>` tag printed by
-`<%= csrf_meta_tags %>` in your application view.
+#### Clearing Persistent Cookies
 
 It is common to use persistent cookies to store user information, with `cookies.permanent` for example. In this case, the cookies will not be cleared and the out of the box CSRF protection will not be effective. If you are using a different cookie store than the session for this information, you must handle what to do with it yourself:
 
@@ -316,6 +349,7 @@ The above method can be placed in the `ApplicationController` and will be called
 Note that _cross-site scripting (XSS) vulnerabilities bypass all CSRF protections_. XSS gives the attacker access to all elements on a page, so they can read the CSRF security token from a form or directly submit the form. Read [more about XSS](#cross-site-scripting-xss) later.
 
 [`config.action_controller.default_protect_from_forgery`]: configuring.html#config-action-controller-default-protect-from-forgery
+[`csrf_meta_tags`]: https://api.rubyonrails.org/classes/ActionView/Helpers/CsrfHelper.html#method-i-csrf_meta_tags
 
 Redirection and Files
 ---------------------
diff --git a/guides/source/working_with_javascript_in_rails.md b/guides/source/working_with_javascript_in_rails.md
@@ -241,17 +241,18 @@ With a WebSocket connection set up on the page that should receive the updates l
 Replacements for Rails/UJS Functionality
 ----------------------------------------
 
-Rails 6 shipped with a tool called UJS that allows developers to override the method of `<a>` tags
-to perform non-GET requests after a hyperlink click and to add confirmation dialogs before
-executing an action. This was the default before Rails 7, but it is now recommended to use Turbo
-instead.
+Rails 6 shipped with a tool called UJS (Unobtrusive JavaScript). UJS allows
+developers to override the HTTP request method of `<a>` tags, to add confirmation
+dialogs before executing an action, and more. UJS was the default before Rails
+7, but it is now recommended to use Turbo instead.
 
 ### Method
 
 Clicking links always results in an HTTP GET request. If your application is
 [RESTful](https://en.wikipedia.org/wiki/Representational_State_Transfer), some links are in fact
-actions that change data on the server, and should be performed with non-GET requests. This
-attribute allows marking up such links with an explicit method such as "post", "put", or "delete".
+actions that change data on the server, and should be performed with non-GET
+requests. The `data-turbo-method` attribute allows marking up such links with
+an explicit method such as "post", "put", or "delete".
 
 Turbo will scan `<a>` tags in your application for the `turbo-method` data attribute and use the
 specified method when present, overriding the default GET action.
@@ -300,3 +301,43 @@ added to the form that the `button_to` helper renders internally:
 ```erb
 <%= button_to "Delete post", post, method: :delete, form: { data: { turbo_confirm: "Are you sure?" } } %>
 ```
+
+### Ajax Requests
+
+When making non-GET requests from JavaScript the `X-CSRF-Token` header is required.
+Without this header requests won't be accepted by Rails.
+
+[Rails Request.JS](https://github.com/rails/request.js) encapsulates the logic
+of adding the request headers that are required by Rails. Just
+import the `FetchRequest` class from the package and instantiate it
+passing the request method, url, options, then call `await request.perform()`
+and do what do you need with the response.
+
+For example:
+
+```javascript
+import { FetchRequest } from '@rails/request.js'
+
+....
+
+async myMethod () {
+  const request = new FetchRequest('post', 'localhost:3000/posts', {
+    body: JSON.stringify({ name: 'Request.JS' })
+  })
+  const response = await request.perform()
+  if (response.ok) {
+    const body = await response.text
+  }
+}
+```
+
+When using another library to make Ajax calls, it is necessary to add the
+security token as a default header yourself. To get the token, have a look at
+`<meta name='csrf-token' content='THE-TOKEN'>` tag printed by
+[`csrf_meta_tags`][] in your application view. You could do something like:
+
+```javascript
+document.head.querySelector("meta[name=csrf-token]")?.content
+```
+
+[`csrf_meta_tags`]: https://api.rubyonrails.org/classes/ActionView/Helpers/CsrfHelper.html#method-i-csrf_meta_tags
