Skip to content

Commit 95f39ea

Browse files
jenspotsjenspots
committed
docs: init readme
1 parent e056123 commit 95f39ea

File tree

3 files changed

+101
-28
lines changed

3 files changed

+101
-28
lines changed

‎README.md

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,75 @@
11
# http-utils-processor-ts
22

3+
[![Build and test with Bun](https://github.com/jenspots/http-utils-processor-ts/actions/workflows/build-test.yml/badge.svg)](https://github.com/jenspots/http-utils-processor-ts/actions/workflows/build-test.yml)
4+
35
Connector Architecture Typescript processors for handling HTTP operations.
6+
7+
## Functions
8+
9+
### [`httpFetch`](./src/index.ts)
10+
11+
Build and execute an HTTP request. Writes the body of the response into a user specified channel.
12+
13+
- `url`: endpoint against which a request is made.
14+
- `writer`: channel into which the resulting data is written.
15+
- `options`: an optional parameter which may include:
16+
- `method` the HTTP method to use. (default: `GET`)
17+
- `headers`: an array of strings to be used as headers in the outgoing request. (default: `[]`)
18+
- `acceptStatusCodes`: an array of strings which lists all the status codes deemed "successful". These strings contain either integer literals such as `"200"`, or ranges such as `"200-300"`. Note that range "`a-b`" is inclusive `a`, exclusive `b`. (default: `["200-300"]`)
19+
- `closeOnEnd`: whether to close the writer stream on end. (default: `true`)
20+
- `timeOutMilliseconds`: maximum time spend waiting for a response before throwing a `HttpFetchError.timeOutError` error. (default: `null`)
21+
- `auth`: object describing which authentication flow to use, as well as its parameters. See below for more info. (default: `null`)
22+
- `cron`: specify the interval at which the function should run as a crontab expression. If `null`, the function only executes once before returning. (default: `null`)
23+
24+
#### Authentication
25+
26+
This package supports some forms of authentication such as HTTP Basic Authentication and the OAuth 2.0 Password Grant. Additional methods may be implemented by extending the abstract [`Auth`](./src/auth/index.ts) class, after which you must define an additional [`AuthConfig`](./src/auth/index.ts) type and extend the [`Auth.from`](./src/auth/index.ts) static method.
27+
28+
##### HTTP Basic Authentication
29+
30+
A simple flow which includes the base64 encoded username and password in each request.
31+
32+
- `type`: must be set to`basic`.
33+
- `username`: your username as string.
34+
- `password`: your plaintext password.
35+
36+
##### OAuth 2.0 Password Grant
37+
38+
Before executing your request, a POST request is sent to the OAuth server in order to obtain a token. The result of which is embedded as a header inside the original request.
39+
40+
- `type`: must be set to `oauth2`
41+
- `endpoint`: the URL of the OAuth 2.0 server.
42+
- `username`: your username as string.
43+
- `password`: your plaintext password.
44+
45+
Note that your credentials are not send to the server you specified in the `url` option of `httpFetch`, but only to the `endpoint` you specified above.
46+
47+
## Errors
48+
49+
All errors thrown in `httpFetch` are of the `HttpFetchError` type, as defined in [`./src/error.ts`](./src/error.ts). This class contains a `HttpUtilsErrorType` enum value which reflects the nature of the error.
50+
51+
## Tests
52+
53+
At the time of writing, tests should be executed using the Bun runtime.
54+
55+
```sh
56+
$ bun run build
57+
$ bun test
58+
```
59+
60+
Some tests interact with real online servers, and may therefore require credentials. These can be supplied inside a `.env` file at the root of the repository.
61+
62+
```shell
63+
# Requires OAuth 2.0 Password Grant
64+
RINF_USERNAME=
65+
RINF_PASSWORD=
66+
67+
# Requires HTTP Basic Auth
68+
WoRMS_USERNAME=
69+
WoRMS_PASSWORD=
70+
71+
# Needs to be `true` in order to execute
72+
BLUE_BIKE=true
73+
```
74+
75+
Additional information can be found [here](./tests/README.md).

‎tests/README.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Test Suite
2+
3+
> [!NOTE]
4+
> This page still needs to be written.

‎tests/online/index.test.ts

Lines changed: 25 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -5,17 +5,14 @@ import { httpFetch } from "../../src";
55
import { writer } from "../writer";
66

77
describe("Real world datasets", () => {
8-
test(
8+
// Retrieve RINF credentials.
9+
const rinfUsername = process.env["RINF_USERNAME"];
10+
const rinfPassword = process.env["RINF_PASSWORD"];
11+
const rinfTest = rinfUsername && rinfPassword ? test : test.skip;
12+
13+
rinfTest(
914
"RINF - success",
1015
async () => {
11-
// Retrieve credentials.
12-
const username = process.env["RINF_USERNAME"];
13-
const password = process.env["RINF_PASSWORD"];
14-
15-
if (!username || !password) {
16-
throw new Error("RINF_USERNAME and RINF_PASSWORD must be set");
17-
}
18-
1916
// Output stream which we'll check for correctness.
2017
const writeStream = writer((output) => {
2118
const json = JSON.parse(output);
@@ -31,8 +28,8 @@ describe("Real world datasets", () => {
3128
{
3229
auth: {
3330
type: "oauth2",
34-
username,
35-
password,
31+
username: rinfUsername!,
32+
password: rinfPassword!,
3633
endpoint: "https://rinf.era.europa.eu/api/token",
3734
},
3835
},
@@ -43,7 +40,7 @@ describe("Real world datasets", () => {
4340
10 * 1000,
4441
);
4542

46-
test(
43+
rinfTest(
4744
"RINF - missing credentials",
4845
async () => {
4946
const func = await httpFetch(
@@ -58,7 +55,7 @@ describe("Real world datasets", () => {
5855
10 * 1000,
5956
);
6057

61-
test(
58+
rinfTest(
6259
"RINF - invalid credentials",
6360
async () => {
6461
const func = await httpFetch(
@@ -81,26 +78,22 @@ describe("Real world datasets", () => {
8178
10 * 1000,
8279
);
8380

84-
test(
81+
// Retrieve WoRMS credentials.
82+
const wormsUsername = process.env["WoRMS_USERNAME"];
83+
const wormsPassword = process.env["WoRMS_PASSWORD"];
84+
const wormsTest = wormsUsername && wormsPassword ? test : test.skip;
85+
86+
wormsTest(
8587
"WoRMS - success",
8688
async () => {
87-
const username = process.env["WoRMS_USERNAME"];
88-
const password = process.env["WoRMS_PASSWORD"];
89-
90-
if (!username || !password) {
91-
throw new Error(
92-
"WoRMS_USERNAME and WoRMS_PASSWORD must be set",
93-
);
94-
}
95-
9689
const func = await httpFetch(
9790
"https://www.marinespecies.org/download/",
9891
new SimpleStream<string>(),
9992
{
10093
auth: {
10194
type: "basic",
102-
username,
103-
password,
95+
username: wormsUsername!,
96+
password: wormsPassword!,
10497
},
10598
},
10699
);
@@ -110,7 +103,7 @@ describe("Real world datasets", () => {
110103
10 * 1000,
111104
);
112105

113-
test(
106+
wormsTest(
114107
"WoRMS - missing credentials",
115108
async () => {
116109
const func = await httpFetch(
@@ -125,7 +118,7 @@ describe("Real world datasets", () => {
125118
10 * 1000,
126119
);
127120

128-
test(
121+
wormsTest(
129122
"WoRMS - invalid credentials",
130123
async () => {
131124
const func = await httpFetch(
@@ -147,7 +140,11 @@ describe("Real world datasets", () => {
147140
10 * 1000,
148141
);
149142

150-
test("BlueBike - success", async () => {
143+
// Check if BLUE_BIKE is defined.
144+
const blueBike = process.env["BLUE_BIKE"];
145+
const blueBikeTest = blueBike === "true" ? test : test.skip;
146+
147+
blueBikeTest("BlueBike - success", async () => {
151148
const writeStream = writer((output) => {
152149
expect(JSON.parse(output).length).toBeGreaterThan(100);
153150
});

0 commit comments

Comments
 (0)