Skip to content

Commit

Permalink
update documentation to reflect new examples structure (#2133)
Browse files Browse the repository at this point in the history
fixes: #2095

Most of the example references are still valid, so I've only updated the
ones that raised 404s. I've also fixed a factual error about field
accessibility.
  • Loading branch information
garypen authored and goto-bus-stop committed Nov 29, 2022
1 parent 70e5c4a commit 5922e90
Show file tree
Hide file tree
Showing 3 changed files with 12 additions and 5 deletions.
7 changes: 7 additions & 0 deletions NEXT_CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,3 +68,10 @@ By [@col](https://github.com/col) in https://github.com/apollographql/router/pul

## 🛠 Maintenance
## 📚 Documentation

### update documentation to reflect new examples structure ([Issue #2095](https://github.com/apollographql/router/pull/2133))

We recently updated the examples directory structure. This fixes the documentation links to the examples. It also makes clear that rhai subgraph fields are read-only, since they are shared resources.

By [@garypen](https://github.com/garypen) in https://github.com/apollographql/router/pull/2133

8 changes: 4 additions & 4 deletions docs/source/customizations/rhai-api.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -167,7 +167,7 @@ fn supergraph_service(service) {

## `Request` interface

All callback functions registered via `map_request` are passed a `request` object that represents the request sent by the client. This object provides the following fields, any of which a callback can modify in-place:
All callback functions registered via `map_request` are passed a `request` object that represents the request sent by the client. This object provides the following fields, any of which a callback can modify in-place (read-write):

```
request.context
Expand All @@ -192,7 +192,7 @@ request.subgraph.uri.host
request.subgraph.uri.path
```

All of these fields are read/write.
These additional fields are shared across all subgraph invocations and are thus read-only.

### `request.context`

Expand Down Expand Up @@ -367,7 +367,7 @@ print(`${response.body.label}`); // logs the response label

A response may contain data (some responses with errors do not contain data). Be careful when manipulating data (and errors) to make sure that response remain valid. `data` is exposed to Rhai as an [Object Map](https://rhai.rs/book/language/object-maps.html).

There is a complete example of interacting with the response data in the [examples/rhai-data-response-mutate directory](https://github.com/apollographql/router/tree/main/examples/rhai-data-response-mutate).
There is a complete example of interacting with the response data in the [examples/data-response-mutate directory](https://github.com/apollographql/router/tree/main/examples/data-response-mutate).

```rhai
print(`${response.body.data}`); // logs the response data
Expand All @@ -385,7 +385,7 @@ Each Error must contain at least:

Optionally, an error may also contain extensions, which are represented as an Object Map.

There is a complete example of interacting with the response errors in the [examples/rhai-error-response-mutate directory](https://github.com/apollographql/router/tree/main/examples/rhai-error-response-mutate).
There is a complete example of interacting with the response errors in the [examples/error-response-mutate directory](https://github.com/apollographql/router/tree/main/examples/error-response-mutate).

```rhai
// Create an error with our message
Expand Down
2 changes: 1 addition & 1 deletion docs/source/customizations/rhai.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -301,4 +301,4 @@ If your router customization needs to do any of these, you can instead create a

The Apollo Router requires that its Rhai engine implements the [sync feature](https://rhai.rs/book/start/features.html) to guarantee data integrity within the router's multi-threading execution environment. This means that [shared values](https://rhai.rs/book/language/fn-closure.html?highlight=deadlock#data-races-in-sync-builds-can-become-deadlocks) within Rhai might cause a deadlock.

This is particularly risky when using closures within callbacks while referencing external data. Take particular care to avoid this kind of situation by making copies of data when required. The [examples/rhai-surrogate-cache-key directory](https://github.com/apollographql/router/tree/main/examples/rhai-surrogate-cache-key) contains a good example of this, where "closing over" `response.headers` would cause a deadlock. To avoid this, a local copy of the required data is obtained and used in the closure.
This is particularly risky when using closures within callbacks while referencing external data. Take particular care to avoid this kind of situation by making copies of data when required. The [examples/surrogate-cache-key directory](https://github.com/apollographql/router/tree/main/examples/surrogate-cache-key) contains a good example of this, where "closing over" `response.headers` would cause a deadlock. To avoid this, a local copy of the required data is obtained and used in the closure.

0 comments on commit 5922e90

Please sign in to comment.