~ushin/hyper-gateway-ushin

#hyper-gateway-ushin - Fork of hyper-gateway

A gateway for talking to hypercore-protocol using the same URL structures as Agregore.

hyper-gateway-ushin adds features which are useful for building programs using the hyper protocol, but which are outside the scope of the standard Fetch API. New features include:

Send requests to the /$/bee API to access the hyperbee k/v store.
GET "full" directory listing with entry metadata in one request. hypercore-fetch-ushin API
Return 403 instead of 404 when requesting a read-only hyperFetch instance for a resource requiring write permissions.
Return X-Drive-Size header containing local disk usage of a hyperdrive.
Send POST request with Cache-Control: no-store header to clear locally cached blobs for a hyperdrive file or directory.
All successful requests for content include X-Drive-Version header with latest drive.version.
Responses when purging a drive now include a Link header.
Return X-Block-Length and X-Block-Length-Downloaded headers for requests to files, but not directories.
Add /$/history API for getting file history in a single request.
GET requests with X-Fully-Replicate request header fully replicate some combination of a drive's inode hyperbee or blobstore.
Performance improvement when checking directory existence.
X-{Next,Previous}-Version-{Exists,Number} response headers offer version metadata. Pass the X-Wait-On-Version-Data request header to load version data from the network before responding. Pass the X-Next-Version-Hint request header to provide a potential next version to test before searching forward through the history.

#Installation

You can download version 3.15.0 of hyper-gateway-ushin from the Codeberg releases page or the SourceHut releases page here for your operating system, move it to your PATH, and make it executable.

The following commands will do this on GNU/Linux systems:

# Paste this into an interactive bash or zsh shell, or save it as a file and run it with sh.

mkdir -p ~/.local/bin/
cd ~/.local/bin/
curl -Lo hyper-gateway-ushin https://codeberg.org/USHIN/hyper-gateway-ushin/releases/download/v3.15.0/hyper-gateway-ushin-linux
# Alternatively, download from SourceHut Builds:
# curl -Lo hyper-gateway-ushin https://git.sr.ht/~ushin/hyper-gateway-ushin/refs/download/v3.15.0/hyper-gateway-ushin-linux
chmod 744 hyper-gateway-ushin

#Usage

hyper-gateway-ushin run --writable true

Options: hyper-gateway-ushin --help run

hyper-gateway-ushin run

Run the gateway

Options:
  --version             Show version number                            [boolean]
  --help                Show help                                      [boolean]
  --writable            Control access to `PUT`       [boolean] [default: false]
  --port                The port to run the server on (HYPE)     [default: 4973]
  --persist             Whether data should be persisted to disk
                                                       [boolean] [default: true]
  --storage-location    The location to store hypercore data
                      [default: "/home/mauve/.local/share/hyper-gateway-nodejs"]
  --silent              Prevent additional logs       [boolean] [default: false]
  --subdomain           Enable serving `example-com.gateway.com/path` as `gatewa
                        y.com/hyper/example.com/path` [boolean] [default: false]
  --subdomain-redirect  Redirect `gateway.com/hyper/domain.here/path` to `domain
                        -here.gateway.com/path`       [boolean] [default: false]

#Routes

GET http://localhost/4973/hyper/:key/*path

You can load data from the gateway by specifying a Hyperdrive key and a path to a file or folder.

The specific HTTP verbs and headers that are supported can be found in hypercore-fetch. Basically you can replace the hyper:// in a URL with http://localhost:4973/hyper/ and it'll work.

#Subdomain / Subdomain-Redirect

When serving contents on a gateway, some sites may be using absolute URLs (e.g. /script.js) which can be messed up when the data is being served from a subdomain (e.g. http://some-gateway.com/hyper/key_here/).

In order to account for this you can add the --subdomain flag which is based on the IPFS Subdomain Gateway Spec, but applied to hyper.

If your domain is https://example.com, instead of using https://example.com/hyper/blog.mauve.moe/index.html to reference a URL, you can instead use https://blog-mauve-moe.example.com/index.html.

You may also place a hypercore public key into the subdomain to have similar effects.

You can also specify the --subdomain-redirect flag which will automatically perform a 301 HTTP redirect to the subdomain version of a URL when a user attempts to load the /hyper/ path.

#Building native binaries

Hyper-gateway-ushin uses the pkg module to compile the node.js code into a single binary that you can distribute on a server.

git clone https://git.sr.ht/~ushin/hyper-gateway-ushin
Install node.js if you haven't already
npm install
npm run build
Look in the dist folder for the platform you want.

#Running `hyper-gateway-ushin` on `GuixSD`

Build hyper-gateway-ushin-linux with npm run build-linux, then run:

#!/usr/bin/env bash
GATE=~/.local/src/hyper-gateway-ushin/dist  # Use your git clone location
DATA=~/.local/share/hyper-gateway-nodejs

guix shell --container --emulate-fhs --network \
     --expression='(list (@@ (gnu packages gcc) gcc) "lib")' \
     --no-cwd --expose=$GATE --share=$DATA \
     -- $GATE/hyper-gateway-ushin-linux \
     run --writable --persist --storage-location $DATA

#FAQ

#How do I run hyper-gateway-ushin as a background process on GNU/Linux + SystemD?

# Paste this into an interactive bash or zsh shell, or save it as a file and run it with sh.

# This will create the service file.
mkdir -p ~/.local/share/systemd/user/
cat << EOF > ~/.local/share/systemd/user/hyper-gateway-ushin.service
[Unit]
Description=hypercore-protocol gateway daemon (for hyperdrive)
Documentation=https://git.sr.ht/~ushin/hyper-gateway-ushin

[Service]
Type=exec
ExecStart=%h/.local/bin/hyper-gateway-ushin --writable true --silent true run
EOF

chmod 644 ~/.local/share/systemd/user/hyper-gateway-ushin.service

systemctl --user daemon-reload
systemctl --user start hyper-gateway-ushin.service
systemctl --user status hyper-gateway-ushin.service

refs

clone