Skip to content

Commit

Permalink
docs: update docs according to style guide
Browse files Browse the repository at this point in the history
  • Loading branch information
nathanosdev committed Dec 19, 2024
1 parent 711e24e commit 760e64a
Show file tree
Hide file tree
Showing 9 changed files with 872 additions and 886 deletions.
8 changes: 4 additions & 4 deletions examples/http-certification/assets/README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,5 @@
# Serving static assets over HTTP

## Overview

This guide walks through an example project that demonstrates how to create a canister that can serve certified static assets (HTML, CSS, JS) over HTTP. The example project presents a very simple single-page JavaScript application. Assets are embedded into the canister when it is compiled.

This is not a beginner's canister development guide. Many fundamental concepts that a relatively experienced canister developer should already know will be omitted. Concepts specific to asset certification will be called out here and can help to understand the [full code example](https://github.com/dfinity/response-verification/tree/main/examples/http-certification/assets).
Expand Down Expand Up @@ -269,7 +267,7 @@ fn certify_all_assets() {

## Serving assets

The `serve_asset` function is responsible for serving assets. It uses the `serve_asset` function from the `AssetRouter` to serve the assets. This function returns an `HttpResponse` that can be returned to the caller.
The `serve_asset` function from the `AssetRouter` is responsible for serving assets. This function returns an `HttpResponse` that can be returned to the caller.

```rust
fn serve_asset(req: &HttpRequest) -> HttpResponse<'static> {
Expand Down Expand Up @@ -342,7 +340,9 @@ fn serve_metrics() -> HttpResponse<'static> {

## Testing the canister

To test the canister, you can use the `dfx` command-line tool. First, run DFX:
This example uses a canister called `http_certification_assets_backend`.

To test the canister, you can use [`dfx`](https://internetcomputer.org/docs/current/developer-docs/getting-started/install) to start a local instance of the replica:

```shell
dfx start --background --clean
Expand Down
12 changes: 6 additions & 6 deletions examples/http-certification/custom-assets/README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,5 @@
# Serving static assets over HTTP (custom)

## Overview

This guide walks through an example project that demonstrates how to create a canister that can serve certified static assets (HTML, CSS, JS) over HTTP. The example project presents a very simple single-page JavaScript application. Assets are embedded into the canister when it is compiled.

This is not a beginner's canister development guide. Many fundamental concepts that a relatively experienced canister developer should already know will be omitted. Concepts specific to HTTP Certification will be called out here and can help to understand the [full code example](https://github.com/dfinity/response-verification/tree/main/examples/http-certification/custom-assets).
Expand Down Expand Up @@ -76,9 +74,9 @@ fn post_upgrade() {
}
```

## CEL Expressions
## CEL expressions

The CEL expression definition is simpler in the case of assets compared to the [JSON API example](https://internetcomputer.org/docs/current/developer-docs/http-compatible-canisters/serving-json-over-http) as the same CEL expression is used for every asset, including the fallback response.
The CEL expression definition is simpler in the case of assets compared to the [JSON API example](https://internetcomputer.org/docs/current/developer-docs/http-compatible-canisters/serving-json-over-http) as the same CEL expression is used for every asset including the fallback response.

```rust
lazy_static! {
Expand Down Expand Up @@ -199,7 +197,7 @@ fn certify_asset_response(
}
```

The next function to look at is another reusable function to certify an asset with a specific encoding. This function will check for a file with an additional file extension matching the requested encoding in the statically included asset directory.
Next is a reusable function to certify an asset with a specific encoding. This function will check for a file with an additional file extension matching the requested encoding in the statically included asset directory.

For example, when certifying `index.html` with `gzip` encoding, this function will check for `index.html.gzip`. If the encoded asset exists, then it is certified using a procedure similar to the previously defined `certify_asset_response` function. The primary difference in this function is where the encoded asset response is stored.

Expand Down Expand Up @@ -550,7 +548,9 @@ fn http_request(req: HttpRequest) -> HttpResponse {

## Testing the canister

To test the canister, you can use the `dfx` command-line tool. First, run DFX:
This example uses a canister called `http_certification_custom_assets_backend`.

To test the canister, you can use [`dfx`](https://internetcomputer.org/docs/current/developer-docs/getting-started/install) to start a local instance of the replica:

```shell
dfx start --background --clean
Expand Down
26 changes: 13 additions & 13 deletions examples/http-certification/json-api/README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,5 @@
# Serving JSON over HTTP

## Overview

This guide walks through an example project that demonstrates how to create a canister that can serve certified JSON over HTTP. The example project presents a very simple REST API for creating and listing to-do items. There is no authentication or persistent storage.

This is not a beginner's canister development guide. Many fundamental concepts that a relatively experienced canister developer should already know will be omitted. Concepts specific to HTTP certification will be called out here and can help to understand the [full code example](https://github.com/dfinity/response-verification/tree/main/examples/http-certification/json-api).
Expand Down Expand Up @@ -42,7 +40,7 @@ fn post_upgrade() {

CEL expressions only need to be set up once and can then be reused until the next canister upgrade. Responses can also be set up once and reused. If the response is static and will not change throughout the canister's lifetime, then it only needs to be certified once. If the response can change, however, then it will need to be re-certified every time it changes.

`DefaultResponseOnlyCelExpression` is used when only the response is to be certified. If the request is also to be certified, then `DefaultFullCelExpression` should be used. Alternatively, the higher-level `DefaultCelExpression` can hold any type of CEL expression using the "Default" scheme. In the future, there may be more schemes, and the higher-level `CelExpression` will be able to hold CEL expressions from those different schemes. It is up to the developers to decide how they want to store and organize their CEL expressions.
`DefaultResponseOnlyCelExpression` is used when only the response is to be certified. If the request is also to be certified, then `DefaultFullCelExpression` should be used. Alternatively, the higher-level `DefaultCelExpression` can hold any type of CEL expression using the "Default" scheme. In the future, there may be more schemes and the higher-level `CelExpression` will be able to hold CEL expressions from those different schemes. It is up to the developers to decide how they want to store and organize their CEL expressions.

In this example, there are two different CEL expressions used, a "full" CEL expression and a "response-only" CEL expression. The "full" CEL expression is used for the certified "todos" and the "response-only" CEL expression for the "Not found" response. For more information on defining CEL expressions, see the relevant section in the [`ic-http-certification` docs](https://docs.rs/ic-http-certification/latest/ic_http_certification/#defining-cel-expressions).

Expand Down Expand Up @@ -83,7 +81,7 @@ lazy_static! {
}
```

## Response Headers
## Response headers

The security headers added to responses are based on the [OWASP Secure Headers project](https://owasp.org/www-project-secure-headers/index.html).

Expand Down Expand Up @@ -380,7 +378,7 @@ fn upgrade_to_update_call_handler(

Upgrading to an `update` call will instruct the HTTP gateway to remake the request as an [`update` call](https://internetcomputer.org/docs/current/references/ic-interface-spec/#http-call). As an update call, the response to this request does not need to be certified. Since the canister's state has changed, however, the static `query` call responses will need to be re-certified. The same functions that certified these responses in the first place can be reused to achieve this.

For creating todo items:
For creating to-do items:

```rust
fn create_todo_item_handler(req: &HttpRequest, _params: &Params) -> HttpResponse<'static> {
Expand Down Expand Up @@ -411,7 +409,7 @@ fn create_todo_item_handler(req: &HttpRequest, _params: &Params) -> HttpResponse
}
```

For updating todo items:
For updating to-do items:

```rust
fn update_todo_item_handler(req: &HttpRequest, params: &Params) -> HttpResponse<'static> {
Expand All @@ -437,7 +435,7 @@ fn update_todo_item_handler(req: &HttpRequest, params: &Params) -> HttpResponse<
}
```

And, finally, for deleting todo items:
And, finally, for deleting to-do items:

```rust
fn delete_todo_item_handler(_req: &HttpRequest, params: &Params) -> HttpResponse<'static> {
Expand Down Expand Up @@ -524,7 +522,9 @@ fn insert_update_route(method: &str, path: &str, route_handler: RouteHandler) {

## Testing the canister

To test the canister, you can use the `dfx` command-line tool. First, run DFX:
This example uses a canister called `http_certification_json_api_backend`.

To test the canister, you can use [`dfx`](https://internetcomputer.org/docs/current/developer-docs/getting-started/install) to start a local instance of the replica:

```shell
dfx start --background --clean
Expand All @@ -533,18 +533,18 @@ dfx start --background --clean
Then, deploy the canister:

```shell
dfx deploy
dfx deploy http_certification_json_api_backend
```

To fetch TODO items:
To fetch to-do items:

```shell
curl -s \
"http://$(dfx canister id http_certification_json_api_backend).localhost:$(dfx info webserver-port)/todos" \
--resolve "$(dfx canister id http_certification_json_api_backend).localhost:$(dfx info webserver-port):127.0.0.1" | jq
```

To add a TODO item:
To add a to-do item:

```shell
curl -s -X POST \
Expand All @@ -554,7 +554,7 @@ curl -s -X POST \
-d '{ "title": "Learn Motoko" }' | jq
```

To update a TODO item:
To update a to-do item:

```shell
curl -s -X PATCH \
Expand All @@ -564,7 +564,7 @@ curl -s -X PATCH \
-d '{ "completed": true }' | jq
```

To delete a TODO item:
To delete a to-do item:

```shell
curl -s -X DELETE \
Expand Down
26 changes: 13 additions & 13 deletions examples/http-certification/skip-certification/README.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,14 @@
# Skipping certification for HTTP responses

## Overview

This guide walks through an example project that demonstrates how to skip HTTP certification for all possible responses from a canister.

WARNING!!! This means that a malicious replica can return whatever data it wants in response to requests directed towards the canister. Think carefully about whether or not this is the right fit for the canister. If certification should only be skipped for certain paths, then check out the ["Serving static assets over HTTP"](https://internetcomputer.org/docs/current/developer-docs/web-apps/http-compatible-canisters/serving-static-assets-over-http) guide where this approach is covered in more detail.
**WARNING** This means that a malicious replica can return whatever data it wants in response to requests directed towards the canister. Think carefully about whether or not this is the right fit for the canister. If certification should only be skipped for certain paths, then check out the ["Serving static assets over HTTP"](https://internetcomputer.org/docs/current/developer-docs/web-apps/http-compatible-canisters/serving-static-assets-over-http) guide where this approach is covered in more detail.

This is not a beginner's canister development guide. Many fundamental concepts that a relatively experienced canister developer should already know will be omitted. Concepts specific to HTTP Certification will be called out here and can help to understand the [full code example](https://github.com/dfinity/response-verification/tree/main/examples/http-certification/skip-certification).
This is not a beginner's canister development guide. Many fundamental concepts that a relatively experienced canister developer should already know will be omitted. Concepts specific to HTTP certification will be called out here and can help to understand the [full code example](https://github.com/dfinity/response-verification/tree/main/examples/http-certification/skip-certification).

## Prerequisites

This is a relatively simple guide so there's no prerequisites as such, but it's recommended to check out the full certification guides to make sure that certification is not a good fit for your project.
This is a relatively simple guide, so there are no prerequisites as such, but it's recommended to check out the full certification guides to make sure that certification is not a good fit for your project.

- [x] Complete the ["Serving static assets over HTTP"](https://internetcomputer.org/docs/current/developer-docs/web-apps/http-compatible-canisters/serving-static-assets-over-http) guide.
- [x] Complete the ["Custom HTTP Canisters"](https://internetcomputer.org/docs/current/developer-docs/http-compatible-canisters/custom-http-canisters) guide.
Expand All @@ -28,7 +26,7 @@ use ic_http_certification::utils::skip_certification_certified_data;

#[init]
fn init() {
set_certified_data(&skip_certification_certified_data());
    set_certified_data(&skip_certification_certified_data());
}
```

Expand All @@ -42,31 +40,33 @@ use ic_http_certification::utils::add_skip_certification_header;

#[query]
fn http_request() -> HttpResponse<'static> {
let mut response = create_response();
    let mut response = create_response();

add_skip_certification_header(data_certificate().unwrap(), &mut response);
    add_skip_certification_header(data_certificate().unwrap(), &mut response);

response
    response
}
```

The call to `data_certificate` returns a certificate that proves the canister's certified data was signed by consensus. This will be included in the header along with all additional information required by the HTTP Gateway to safely skip verification of this response.

## Testing the canister

Start DFX:
This example uses a canister called `http_certification_skip_certification_backend`.

To test the canister, you can use [`dfx`](https://internetcomputer.org/docs/current/developer-docs/getting-started/install) to start a local instance of the replica:

```shell
dfx start --background --clean
```

Deploy the canister:
Then, deploy the canister:

```shell
dfx deploy http_certification_skip_certification_backend
```

Make a request to the canister using cURL:
Make a request to the canister using curl:

```shell
curl -s http://localhost:$(dfx info webserver-port)?canisterId=$(dfx canister id http_certification_skip_certification_backend) | jq
Expand All @@ -80,7 +80,7 @@ You should see output similar to the following:
}
```

Alternatively, print the URL in the terminal and then open in a browser:
Alternatively, print the URL in the terminal and then open it in a browser:

```shell
echo http://localhost:$(dfx info webserver-port)?canisterId=$(dfx canister id http_certification_skip_certification_backend)
Expand Down
Loading

0 comments on commit 760e64a

Please sign in to comment.