MDN のサンプルサーバー

MDN は内蔵のライブサンプルシステムを提供しており、単純な (時にはそう単純でない) コードのサンプルをその出力と共にページの中で表示する機能を提供していますが、サーバーへの通信を必要とするサンプルもあります。私たちは MDN サンプルサーバーを用意し、このような、またその他の問題も合わせて、解決することにしました。 この記事は、そのサンプルサーバーを利用するためのガイドです。

想定するユースケース

たいていのサンプルは組み込みのライブサンプルシステムで表現できますが、例外もあります。サンプルサーバーの利用が必要となる理由は下記の通りです。

  • サンプルにサーバー上で永続的に実行されるコードが必要、例えば WebSocket サーバーにはサーバーコンポーネントと、サンプルサーバー上のクライアントコンポーネントもあるなど。
  • MDN wiki のコンテンツでは動かない技術を使ったサンプルや、読み手がコンテンツに集中する能力に影響するようなものは明らかに候補となります; これにはサウンド効果やメディアや大量のアニメーションを再生するものが含まれます。
  • MDN でホストできないようなリソースにアクセスする必要があるサンプルはサンプルサーバーに置かれます。

サンプルへの参照を追加する

各サンプルのコードは GitHub で管理されており、そのすべてのサンプルの実行可能/使用可能なインストールアクセスを提供するサーバーを持っています。

高度なサンプルに貢献する

サンプルサーバーに置かれたサンプルに貢献するには、GitHub の MDN サンプルサーバーリポジトリー をフォークする必要があります。現在、すべてのサンプルは GitHub の同じリポジトリーにあります。

それぞれのサンプルは s/ ディレクトリーの下に自身のディレクトリーを持っています。新しいサンプルを作るには、そこに適切な名前のディレクトリーを追加します。例えば、ちょっとしたゲームを実装するための Fetch API の使い方を示す例であれぱ、s/fetch-trivia にサンプルを置いても良いでしょう。

高度なサンプルの構造

それぞれのサンプルに一つの必須ファイルがあります (これは皮肉にもまだ使われていませんが、すぐ使われるため入れておいてください)。 manifest.json というマニフェストファイルで、これはサンプルを説明し、サンプルサーバー自体からと、これをメンテ・使用するツールから使われるメタデータを提供します。その他のすべてはオプションです。もっと詳しく見ていきましょう。

マニフェストファイル: manifest.json

マニフェストファイルは第一に、サンプルのリストをビルドするのに使われますが、最終的には各サンプルのスタートアップとシャットダウンプロセスを改良することに使われるでしょう。これは次のような JSON オブジェクトです。

{
  "name": "WebSocket based chat server with WebRTC video chat support",
  "docsUrl": "https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API/Signaling_and_video_calling",
  "description": "Uses Node.js to set up a WebSocket-based chat server, and provides a web page you can use to join the chat. Adds a feature to start a video call with another chat participant."
}

現在オブジェクトには 3 つの項目があり、すべてが必須です (まだ使用してないですが、すぐ使います)。

name
実例の名前です。例の比較的短い名前であるべきです。
docsUrl
この例を詳しく扱っている MDN の主なページの URL です。例が複数のページから参照されている場合、「メイン」ページ (または存在するならランディングページ) のアドレスであるべきです。
description
実例を説明する長めの文で、これがデモする技術についての情報を含みます。

起動時にサンプルを動かす: startup.sh

サンプルサーバーの起動時やサンプルの再起動時には、各サンプルのベースディレクトリーがスキャンされ、 startup.sh という名前のシェルスクリプトファイルが存在するかどうかが確認されます。このファイルが存在すると、そのファイルが実行され、サンプルがサポートファイルをインストールしたり、スクリプトを実行したり、サンプルをサポートするために必要なサーバープロセスを起動したりする機会が与えられます。例えば、 WebSocket chat サンプル (en-US)の startup.sh スクリプトは次のようになります。

npm install websocket
node chatserver.js

1 行目は Node のパッケージマネージャーである npm を使用して、 websocket というモジュールをインストールし、これが WebSocket サーバーを生成したり対話したりすることのサポートを提供します。

2 行目は、実際にサーバープロセスを起動します。これは、バックグラウンドで起動し実行される JavaScript スクリプトとして実装されています。

Node.js モジュールを使う: package.json

Node モジュールをプロジェクトで使用するには、 package.json ファイルを追加する必要があります。ここにはサンプルに関する情報だけでなく、依存関係のリストも含まれており、 Node パッケージマネージャー (npm) によって依存関係がインストールされるようになっています。

オプションのファイル

もちろん、他のファイルがあっても構いません。明らかな候補としては、サンプルを閲覧したユーザーに何らかのコンテンツを見せるための index.html ファイル、スタイルシート、サポート用の HTML や JavaScript ファイル、画像やその他のメディアなどがあります。

サンプルの投稿

サンプルを完成させてテストしたら、それを提出してテストを受け、最終的に本番のサンプルサーバーにインストールできるようにしましょう。この作業は、 Github の標準的なプルリクエストプロセスを用いて行います。

ヒントとエラッタ

サンプルサーバー自体がまだ完成していないため、サンプルの動作には癖や問題があります。ここでは、潜在的な最悪の問題を回避するためのヒントをいくつかご紹介します。

ポート番号

サンプルがネットワークポートを使用する必要がある場合、他のサンプル (またはサーバー上のシステムサービス) が既に使用しているポートを不用意に使用しないように注意する必要があります。将来的には、サンプルのマニフェストにポート番号を要求する項目が設けられ、システムがポート番号を割り当てて、どれが使われていてどれが使われていないかを記録するようになる予定です。それまでは、つま先を踏まないように気をつけてください。

進行中の作業

このページそのもの、そしてここに記述されているサーバーについては、現在作業中です。