Open Network HTTP Store
This module aims to provide a common way to access files over HTTP, the underlying store may communicate over different transports, while adopting the HTTP specification.
Installation
Currently we have only distributed this module via npm using
the package name @opennetwork/http-store
This module relies on @opennetwork/http-representation
as a peer dependency which is also distributed via npm
Installation via the npm CLI
Using the module directly
npm install --save @opennetwork/http-representation @opennetwork/http-store
Using the module within another module
npm install --save-dev @opennetwork/http-representation @opennetwork/http-store
Once you have added the module to your devDependencies
, include the module
in your peerDependencies
so the same version is used across the stack.
Usage
FS Store
To utilise the FSStore
you need to instantiate an instance using some options, this is via a single object
This is the type definition for the options:
type FSStoreOptions = {
fs: typeof fs;
rootPath?: string;
getPath?: (url: string) => string | Promise<string>
statusCodes: {
[errorCode: number]: string | undefined;
[errorCode: string]: string | undefined;
};
getExternalResource?: (url: string, request: Request) => Promise<Response>
};
-
fs
, an instance offs
, this could be either the Node.js implementation offs
, or a compatible module like hyperdrive (Required) -
rootPath
, the root path where we are going to store & read files from (Required ifgetPath
is not present) -
getPath
, a function that can map the received url's to a path within the file system (Required ifrootPath
is not present) -
statusCodes
, an object containing all available status codes, this could be the Node.js modulehttp
viahttp.STATUS_CODES
-
getExternalResource
, a function that can resolve external dependencies, this is used forCOPY
requests when the resource is external, if not provided the status501 - Not Implemented
will be returned to the consumer
Example
example.js
:
import { Request } from "@opennetwork/http-representation";
import { Store } from "@opennetwork/http-store";
export async function runExample(store: Store) {
const documentUrl = "https://store.open-network.app/example/document.txt";
const documentContent = Buffer.from("test", "utf-8");
const putResponse = await store.fetch(
new Request(
documentUrl,
{
method: "PUT",
body: documentContent,
headers: {
"Content-Type": "text/plain"
}
}
)
);
assert(putResponse.ok);
const getResponse = await store.fetch(
new Request(
documentUrl,
{
method: "GET",
headers: {
"Accept": "text-plain"
}
}
)
);
assert(getResponse.ok);
assert(getResponse.body instanceof Uint8Array);
assert(getResponse.body.toString() === documentContent.toString());
}
import { FSStore } from "@opennetwork/http-store";
import fs from "fs";
import http from "http";
import assert from "assert";
import { runExample } from "./example.js"
runExample(
new FSStore({
fs,
rootPath: "./store",
statusCodes: http.STATUS_CODES
})
)
.then(() => console.log("Complete!"))
.catch((error) => console.error("Received error!", error));
Remote Store
A remote store is just a way of representing a store that needs to be invoked across a transport (like HTTP), the remote store only takes one function, which is used to fetch the remote resource.
The accepted fetcher function will receive a request, and is expected to return a response:
type Fetcher = (request: Request) => Promise<Response>;
Example
(Using the same example.js
implementation as FSStore
)
import { RemoteStore } from "@opennetwork/http-store";
import { Resposne } from "@opennetwork/http-representation";
import fs from "fs";
import http from "http";
import assert from "assert";
import { runExample } from "./example.js"
import fetch from "node-fetch";
runExample(
new RemoteStore(
async (request) => {
const response = fetch(request.url, request);
return new Resposne(
await response.buffer(),
{
status: response.status,
statusText: response.statusText,
headers: response.headers.raw()
}
);
}
)
)
.then(() => console.log("Complete!"))
.catch((error) => console.error("Received error!", error));