P2Pブラウザ「Beaker」のドキュメント(開発者)を和訳してみた



Beakerは、https://beakerbrowser.com/ にて公開されているHypercoreと呼ばれるピアツーピアのプロトコルを用いたブラウザです。このHypercoreと同様のものとしてIPFS(Interplanetary File System) https://ipfs.io/ があります。


![beaker.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2520265/e9822ead-8714-d664-9212-45691ba51819.png)


IPFSは、Brave Browserに組み込まれていてHypercoreと比較し知名度が高いと思われます。著者もIPFSの方を先に知っていました。会社勤めを辞めたおり、Hacker NewsにてこのBeakerを知り、IPFSと比較して日本語の記事がまるで検索されなかったので、暇つぶしも兼ねて https://beakerbrowser.com/ にて公開されている記事を和訳してみた次第です。

なお、
- 和訳は、[DeepL](https://www.deepl.com/) にて英語から日本語に訳し、日本語文章としておかしな部分が無いように調整した程度のものです。単語の統一性まで確認するほどの厳密な和訳作業はしていません。


- 「[P2Pブラウザ「Beaker」のドキュメント(APIs)を和訳してみた](https://qiita.com/bitlonginthetooth/items/1768d06c40cbd95326a3)」の続きです。

# 開発者


## ハイパードライブ入門編

Hyperdriveはピアツーピアのネットワークです。概念的にはBitTorrentと共通する部分が多く、以下のようなものがあります。

- ハイパードライブは、どのユーザーのデバイスからでもホストできます。
- すべてのデータは暗号化により認証される
- ピアは、DHTを使用して発表され、発見される
- ピアはドライブを「共同ホスト」して帯域幅に貢献できます。

しかし、重要な違いがたくさんあります。

- ドライブは公開鍵のURLでアドレス指定（例：hyper:/12345...af
- ファイルの真正性を証明するために、Merkleツリーのチェックサムだけでなく、署名が使用される
- ドライブ内のファイルは変更可能
- ドライブへの変更履歴はログに保存される
- ピアは公開鍵のURLを知っている場合のみ、あなたのドライブに接続できます

この文書では、アプリケーションでHyperdriveを理解するために必要な多くの概念について説明します。


## メカニズム

各ハイパードライブ（または「ドライブ」）は、基本的にネットワークに接続されたフォルダーです。ドライブには、ファイル、フォルダー、シンボリックリンク、およびマウントを含めることができます。

Beakerのハイパードライブは、Webコンテンツ（HTML/JS/CSS）を実行できます。

## 公開鍵 URLs

すべてのドライブは、しばしば単に "キー "と呼ばれる公開キーによって識別されます。このキーは、64文字の16進文字列としてエンコードされています。

URLでは、このキーがドメインとして機能します。URLの残りの部分は、パス、クエリ、ハッシュセグメントを含め、通常のHTTPS URLとして動作します。

```
hyper://5f2fb811a6071237aa6e83db87edc433e861808f781a2a070ed8a5503fb6514e/
```


## オーサリングの制御
ドライブに変更を加えるには、デバイスがドライブの秘密鍵を所有している必要があります。

```
現在、秘密鍵は機器間やユーザー間で共有することはできません。このようなコラボレーション（「マルチライター」と呼ばれる）には、現在進行中のプロトコルへの追加が必要です。
```

## ホスティング/コ・ホスティング
ドライブは、複数のデバイスでホストできます。これはしばしば「シーディング」と呼ばれますが、Hyperdriveでは「コ・ホスティング」と呼びます。デバイスは、「DHT Swarm」上で自分自身を発表することによってホストし、他のユーザーにドライブのコンテンツを提供できるデバイスとして、そのIPを効果的にリストアップします。


## キャッシング
ドライブのコンテンツにアクセスする際、Hyperdriveは自動的にローカルデバイスにコンテンツをキャッシュします。これは、変更がない限り、その後の読み込みにネットワークアクセスを必要としないことを意味します。ネットワークスタックは変更を監視し、最新のコンテンツが利用可能な場合、デフォルトでローカルキャッシュを使用します。

## バージョン管理
ハイパードライブは、書き込みごとにインクリメントされるバージョンカウンターを保持しています。また、以前のバージョンを読み込んだり、バージョン間の "差分 "を取ることも可能です。しかし、Gitとは異なり、Hyperdriveにはブランチがありません。歴史は一本道です。

ドライブのバージョンは、キーの後のURLで指定できます。それは次のような形式をとります。


```
hyper://{key}+{version}/{path...}
```
参照: drive(), getInfo(), diff()

## マウント
「マウント」はハイパードライブ間のシンボリックリンクのようなものです。また、概念的にはGitのサブモジュールに似ています。あるドライブを別のドライブのサブフォルダーとして動作させます。

ドライブのマウントには、バージョンを指定することも、指定しないことも可能です。バージョンを指定しない場合、マウントされたフォルダーにアクセスする際には常に最新の内容が提供されます。

参照: stat(), mount(), unmount()

## ファイルのK/Vメタデータ
すべてのファイルは、有用な情報を格納するために使用できるキーと値のメタデータを持っています。たとえば、一般的なメタデータの K/V は href キーであり、これはファイルがインターネット上の他のリソースを参照して書かれていることを示すために使用されます。

stat(), writeFile(), updateMetadata(), deleteMetadata() も参照してください。

## クエリ
Hyperdrive APIには、複数のフォルダーを素早くスキャンするためのquery()メソッドがあります。パス、メタデータ、エントリーの種類、マウント先に対してフィルタリングできます。また、出力をソートしたり、ページ分割のためにリミット/オフセットを適用することもできます。


---
## Index.json マニフェスト

すべてのハイパードライブは、/index.jsonにマニフェスト ファイルを持ちます。このファイルは、ドライブのタイトルや説明など、さまざまな種類のメタデータを保存するためにブラウザによって使用されます。

注： マニフェスト・スキーマはまだ開発中であり、変更される可能性があります。

マニフェストの例

``` json
{
  "title": "My Hyper Website",
  "description": "An example hyperdrive"
}
```

### Manifest schema

#### .title
ドライブのタイトルを示す文字列。

#### .description
ドライブの内容の説明を示す文字列。

#### .forkOf
このドライブがフォークしたドライブのURLを示す文字列。

#### .csp
すべてのドライブリソースで使用するContent-Security Policyヘッダーを指定する文字列。


---
## コンテントタイプのネゴシエーション
ファイルによっては、拡張子を付けない方が正しくサービスされる場合があります。と入力するよりも

``` html
<img src="/thumb.png">
```
次のように入力したほうがよいでしょう：

``` html
<img src="/thumb">
```

これは、サイトがどの拡張子を使うかわからない場合に便利です。画像の場合、.png, .jpg, .jpeg, .gifかもしれません。拡張子を含めないことで、そのサイトが使用するフォーマットを取得できます。

動作は以下の通りです。

- text/html. Will match .html and .md.
- text/css. Will match .css.
- image/*. Will match .png, .jpg, .jpeg, and .gif.



## フロントエンド (.ui フォルダー)

hyper://の標準的な動作は、URLで参照されるどのファイルでも提供することです。これは単純な使用例ではうまくいきますが、2つの使用例で苦労します。

1. 各ページに一貫したテーマとテンプレートを適用する必要があるサイト。
2. ファイルが存在しない場所でもインターフェイスを提供する必要があるアプリケーション（Single Page Applicationパターンのように）。

これを解決するために、hyper://プロトコルは "Frontends "と呼ばれる動作をサポートしています。

### フロントエンドのしくみ

フロントエンドは、/.ui/ui.htmlにあるhtmlファイルです。このファイルは、サイトの一貫したインターフェイスを提供するために使用されます。次のような場合、ターゲットファイルではなく、このファイルが提供されます。

- ターゲットURLにファイルが存在しない。
- 対象URLにファイルが存在しない場合  対象URLがフォルダーである場合
- Accept」ヘッダーにtext/htmlが含まれている（ブラウザが「ページ」を要求していることを示す）。


フロントエンドは、すべてのページ表示を効果的に上書きするため、サイトの作者が望むものを何でもレンダリングできます。よくあるパターンは、JavaScriptを使って、window.location.pathnameで参照されているファイルを読み取り、それをUIに配置することです（この例のスニペットのように）。

```
/.ui/ui.html
```

``` html
<body>
  <main></main>
</body>
<script>
async function setup () {
  var main = document.querySelector('main')
  if (location.pathname.endsWith('.html')) {
    let html = await beaker.hyperdrive.readFile(location.pathname).catch(e => `<h1>404 not found<h1>`)
    main.innerHTML = html
  } else if (location.pathname.endsWith('.jpg')) {
    main.innerHTML = `<img src="${location.pathname}">`
  } // etc...
}
setup()
</script>
```


### マウントされたフロントエンド

Frontendsの利点は、サブフォルダーに格納されることです。これにより、フロントエンドは /.uiにマウントされた独自のHyperdriveサイトとします。

```
|12345..af> mount $my_frontend_drive_url /.ui
```

フロントエンド・ハイパードライブは、複数のサイトで公開・共有できます。


---
## Goto Files

.gotoファイルとは、Beakerがさまざまな場面で使用するショートカットファイルです。たとえば、すべてのブックマークは、ユーザーのシステムドライブに　.gotoファイルとして保存されます。

.gotoファイルには、内容は期待できません。その代わり、2つのメタデータ属性を持っています。

- title. .gotoファイルによって指し示されるリソースのタイトル。
- href。.gotoファイルが指すリソースのURL。

.gotoファイルがhyper:// プロトコルで訪問されると、Beakerは自動的にそのhref値にリダイレクトします。

```
Webterm を使って mkgoto コマンドで .goto ファイルを作成することができます。
```