Add http.fetch API and examples (#84)

Author: mattjohnsonpint

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 - Fixed threshold logic bug in `inference.classifyText` [#76](https://github.com/gohypermode/functions-as/pull/76)
 - Align `hypermode.json` examples to changes in manifest schema [#79](https://github.com/gohypermode/functions-as/pull/79) [#80](https://github.com/gohypermode/functions-as/pull/80) [#81](https://github.com/gohypermode/functions-as/pull/81)
+- Add `http.fetch` API [#84](https://github.com/gohypermode/functions-as/pull/84)
 
 # 2024-04-25 - Version 0.6.1
 

examples/classification/README.md

@@ -1,5 +1,5 @@
 # Hypermode Classification Example Plugin
 
-This is an example shows how to invoke a model that can perform classification.
+This example shows how to invoke a model that can perform classification.
 
 See [./assembly/index.ts](./assembly/index.ts) for the implementation.

examples/embedding/README.md

@@ -1,5 +1,5 @@
 # Hypermode Embedding Example Plugin
 
-This is an example shows how to invoke a model that can calculate vector embeddings.
+This example shows how to invoke a model that can calculate vector embeddings.
 
 See [./assembly/index.ts](./assembly/index.ts) for the implementation.

examples/graphql/README.md

@@ -1,6 +1,6 @@
 # Hypermode GraphQL Example Plugin
 
-This is an example shows how to call a GraphQL endpoint to execute queries and mutations.
+This example shows how to call a GraphQL endpoint to execute queries and mutations.
 
 It uses a Dgraph, at the host configured in the `hypermode.json` manifest.
 

examples/http/.eslintrc.json

@@ -0,0 +1,12 @@
+{
+  "env": {
+    "es6": true
+  },
+  "extends": ["eslint:recommended", "plugin:@typescript-eslint/recommended"],
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": "latest",
+    "sourceType": "module"
+  },
+  "plugins": ["@typescript-eslint"]
+}

examples/http/.prettierrc

@@ -0,0 +1,3 @@
+{
+  "plugins": ["assemblyscript-prettier"]
+}

examples/http/README.md

@@ -0,0 +1,10 @@
+# Hypermode HTTP Example Plugin
+
+This example shows how to call an external host via HTTP `fetch`.
+
+See [./assembly/index.ts](./assembly/index.ts) for the implementation.
+
+Note that any host used by the `fetch` function must have a base URL defined
+as a host in the [`hypermode.json`](./hypermode.json) manifest file.
+This is a security measure that prevents arbitrary hosts from being called
+based solely on function input values.

examples/http/asconfig.json

@@ -0,0 +1,19 @@
+{
+  "extends": "./node_modules/@assemblyscript/wasi-shim/asconfig.json",
+  "options": {
+    "transform": ["@hypermode/functions-as/transform", "json-as/transform"],
+    "exportRuntime": true
+  },
+  "targets": {
+    "debug": {
+      "sourceMap": true,
+      "debug": true
+    },
+    "release": {
+      "optimizeLevel": 3,
+      "shrinkLevel": 0,
+      "converge": false,
+      "noAssert": false
+    }
+  }
+}

examples/http/assembly/classes.ts

@@ -0,0 +1,33 @@
+// For now, this import is required when we use @json, even if we're not calling
+// methods on the JSON class.  It will be fixed in the future.
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import { JSON } from "json-as";
+
+// These classes are used by the example functions in the index.ts file.
+
+@json
+export class Quote {
+
+  @alias("q")
+  quote!: string;
+
+
+  @alias("a")
+  author!: string;
+}
+
+export class Image {
+  contentType!: string;
+  data!: ArrayBuffer;
+}
+
+
+@json
+export class Issue {
+  title!: string;
+  body!: string;
+
+  // The URL of the issue on GitHub, after the issue is created.
+  @alias("html_url")
+  url: string | null = null;
+}

examples/http/assembly/index.ts

@@ -0,0 +1,88 @@
+import { http } from "@hypermode/functions-as";
+import { Quote, Image, Issue } from "./classes";
+
+// This function makes a simple HTTP GET request to example.com,
+// and returns the HTML text of the response.
+export function getExampleHtml(): string {
+  const response = http.fetch("https://example.com/");
+  return response.text();
+}
+
+// This function makes a request to an API that returns data in JSON format,
+// and returns an object representing the data.
+// It also demonstrates how to check the HTTP response status.
+export function getRandomQuote(): Quote {
+  const request = new http.Request("https://zenquotes.io/api/random");
+
+  const response = http.fetch(request);
+  if (!response.ok) {
+    throw new Error(
+      `Failed to fetch quote. Received: ${response.status} ${response.statusText}`,
+    );
+  }
+
+  // The API returns an array of quotes, but we only want the first one.
+  return response.json<Quote[]>()[0];
+}
+
+// This function makes a request to an API that returns an image, and returns the image data.
+export function getRandomImage(width: i32, height: i32): Image {
+  const url = `https://picsum.photos/${width}/${height}`;
+  const response = http.fetch(url);
+  const contentType = response.headers.get("Content-Type")!;
+
+  return {
+    contentType,
+    data: response.body,
+  };
+}
+
+// This function demonstrates a more complex HTTP call.
+// It makes a POST request to the GitHub API to create an issue.
+// See https://docs.github.com/en/rest/issues/issues?apiVersion=2022-11-28#create-an-issue
+// To use it, you must add a GitHub personal access token to your Hypermode secrets.
+// Create a fine-grained token at https://github.com/settings/tokens?type=beta with access
+// to write issues to the repository you want to use.
+//
+// NOTE: do not pass the Authorization header in the request.
+// Instead, set the authHeader in the hypermode.json manifest file to "Authorization".
+// The Hypermode Runtime will retrieve the token from your secrets and add it to the request.
+// The secret should be prefixed with "Bearer ".
+// In development, you can set the token as an environment variable, in an .env file if desired.
+// Example: HYP_HOST_KEY_GITHUB=Bearer <your-token>
+export function createGithubIssue(
+  owner: string,
+  repo: string,
+  title: string,
+  body: string,
+): Issue {
+  // The URL for creating an issue in a GitHub repository.
+  const url = `https://api.github.com/repos/${owner}/${repo}/issues`;
+
+  // Create a new request with the URL, method, and headers.
+  const request = new http.Request(url, {
+    method: "POST",
+    headers: http.Headers.from([
+      // Do not pass an Authorization header here. See note above.
+      ["Accept", "application/vnd.github+json"],
+      ["X-GitHub-Api-Version", "2022-11-28"],
+      ["Content-Type", "application/json"],
+    ]),
+
+    // The request body will be sent as JSON from the Issue object passed here.
+    body: http.Content.from(<Issue>{ title, body }),
+  } as http.RequestOptions);
+
+  // Send the request and check the response status.
+  // NOTE: If you are using a private repository, and you get a 404 error, that could
+  // be an authentication issue. Make sure you have created a token as described above.
+  const response = http.fetch(request);
+  if (!response.ok) {
+    throw new Error(
+      `Failed to create issue. Received: ${response.status} ${response.statusText}`,
+    );
+  }
+
+  // The response will contain the issue data, including the URL of the issue on GitHub.
+  return response.json<Issue>();
+}