Merge pull request #582 from demergent-labs/566_http

Implemented outgoing http requests with a couple examples

.github/workflows/test.yml

@@ -65,6 +65,7 @@ jobs:
                     "examples/cross_canister_calls",
                     "examples/cycles",
                     "examples/date",
+                    "examples/ethereum_json_rpc",
                     "examples/func_types",
                     "examples/generators",
                     "examples/heartbeat",
@@ -93,6 +94,7 @@ jobs:
                     "examples/notify_raw",
                     "examples/null_example",
                     "examples/optional_types",
+                    "examples/outgoing_http_requests",
                     "examples/pre_and_post_upgrade",
                     "examples/primitive_types",
                     "examples/principal",
@@ -125,6 +127,8 @@ jobs:
     basic-integration-tests:
         needs: release-candidate-deploy
         runs-on: ubuntu-latest
+        env:
+            ETHEREUM_URL: ${{ secrets.ETHEREUM_URL }}
         strategy:
             fail-fast: false # We want to see which example tests succeed and which ones fail, we don't want one example test to cancel the rest
             matrix:
@@ -174,7 +178,7 @@ jobs:
               run: npm link
             - if: ${{ needs.release-candidate-deploy.outputs.should_run_tests }}
               working-directory: ${{ matrix.example_directories }}
-              run: dfx start --clean --background
+              run: dfx start --clean --background --enable-canister-http
             - if: ${{ needs.release-candidate-deploy.outputs.should_run_tests }}
               shell: bash -l {0}
               working-directory: ${{ matrix.example_directories }}

README.md

@@ -47,6 +47,7 @@ Most of Azle's documentation is currently found in this README. The Azle Book, s
 -   [Canister APIs](#canister-apis)
 -   [Call APIs](#call-apis)
 -   [Stable Memory](#stable-memory)
+-   [Special APIs](#special-apis)
 -   [JS APIs](#js-apis)
 -   [Feature Parity](#feature-parity)
 -   [Benchmarks](#benchmarks)
@@ -2293,6 +2294,50 @@ export function stable_write(offset: nat32, buf: blob): Update<void> {
 }
 ```
 
+### Special APIs
+
+#### Outgoing HTTP Requests
+
+This feature is available in `dfx 0.11.0` with the `--enable-canister-http` flag but is not yet live on the IC.
+
+Examples:
+
+-   [ethereum_json_rpc](/examples/ethereum_json_rpc)
+-   [outgoing_http_requests](/examples/outgoing_http_requests)
+
+```typescript
+import { CanisterResult, ic, ok, Query, Update } from 'azle';
+import { HttpResponse, ManagementCanister } from 'azle/canisters/management';
+
+export function* xkcd(): Update<HttpResponse> {
+    const max_response_bytes = 1_000n;
+
+    // TODO this is just a hueristic for cost, might change when the feature is officially released: https://forum.dfinity.org/t/enable-canisters-to-make-http-s-requests/9670/130
+    const cycle_cost_base = 400_000_000n;
+    const cycle_cost_per_byte = 300_000n; // TODO not sure on this exact cost
+    const cycle_cost_total =
+        cycle_cost_base + cycle_cost_per_byte * max_response_bytes;
+
+    const http_result: CanisterResult<HttpResponse> =
+        yield ManagementCanister.http_request({
+            url: `https://xkcd.com/642/info.0.json`,
+            max_response_bytes,
+            http_method: {
+                GET: null
+            },
+            headers: [],
+            body: null,
+            transform_method_name: 'xkcd_transform'
+        }).with_cycles(cycle_cost_total);
+
+    if (!ok(http_result)) {
+        ic.trap(http_result.err ?? 'http_result had an error');
+    }
+
+    return http_result.ok;
+}
+```
+
 ### JS APIs
 
 This section will describe various JS APIs that may need special explanation.

canisters/management.ts

@@ -14,15 +14,15 @@
 // The original license for the DFINITY code can be found here: https://github.com/dfinity/ic/blob/master/LICENSE
 // This file contains derivative works licensed as MIT: https://github.com/demergent-labs/azle/blob/main/LICENSE
 
-// TODO created based on this documentation: https://smartcontracts.org/docs/interface-spec/index.html#ic-candid
-// TODO I would like to find the canonical did file in the ic repository
+// Taken in part from: https://github.com/dfinity/interface-spec/blob/master/spec/ic.did
 
 import {
     blob,
     Canister,
     CanisterResult,
     ic,
     nat,
+    nat64,
     Opt,
     Principal,
     Variant
@@ -124,6 +124,32 @@ export type ProvisionalTopUpCanisterArgs = {
     amount: nat;
 };
 
+export type HttpRequestArgs = {
+    url: string;
+    max_response_bytes: Opt<nat64>;
+    http_method: HttpMethod;
+    headers: HttpHeader[];
+    body: Opt<blob>;
+    transform_method_name: Opt<string>;
+};
+
+export type HttpMethod = Variant<{
+    GET: null;
+    HEAD: null;
+    POST: null;
+}>;
+
+export type HttpHeader = {
+    name: string;
+    value: string;
+};
+
+export type HttpResponse = {
+    status: nat64;
+    headers: HttpHeader[];
+    body: blob;
+};
+
 export type Management = Canister<{
     create_canister(
         args: CreateCanisterArgs
@@ -139,6 +165,7 @@ export type Management = Canister<{
     delete_canister(args: DeleteCanisterArgs): CanisterResult<void>;
     deposit_cycles(args: DepositCyclesArgs): CanisterResult<void>;
     raw_rand(): CanisterResult<blob>;
+    http_request(args: HttpRequestArgs): CanisterResult<HttpResponse>;
     provisional_create_canister_with_cycles(
         args: ProvisionalCreateCanisterWithCyclesArgs
     ): CanisterResult<ProvisionalCreateCanisterWithCyclesResult>;
@@ -147,6 +174,6 @@ export type Management = Canister<{
     ): CanisterResult<void>;
 }>;
 
-export const ManagementCanister = ic.canisters.Management<Management>(
+export const ManagementCanister: Management = ic.canisters.Management(
     Principal.fromText('aaaaa-aa')
 );

examples/ethereum_json_rpc/.gitignore

@@ -0,0 +1,3 @@
+.dfx
+node_modules
+target

examples/ethereum_json_rpc/dfx.json

@@ -0,0 +1,15 @@
+{
+    "canisters": {
+        "ethereum_json_rpc": {
+            "type": "custom",
+            "build": "npx azle ethereum_json_rpc",
+            "root": "src",
+            "ts": "src/index.ts",
+            "candid": "src/index.did",
+            "wasm": "target/wasm32-unknown-unknown/release/ethereum_json_rpc.wasm",
+            "declarations": {
+                "output": "test/dfx_generated/ethereum_json_rpc"
+            }
+        }
+    }
+}