ユースケース

このページでは、ユースケースごとに、CIが実行するサンプルをこのページかリンク先のガイドに載せるか、テストしていないことと、その理由を書いています。サンプルは、このリポジトリのテストのファイルと、そのテストがCIのたびに比べるレスポンスを示します。サンプルの仕組みは、サイトの構想の3.5にあります。

Hello world

contentハンドラがレスポンスを書きます。

server {
    listen 18161;

    location /hello {
        mruby_content_handler build/nginx/html/guide_hello.rb;
    }
}

Nginx.echo "Hello World"

GET /hello HTTP/1.1
Host: 127.0.0.1:18161
Connection: close

HTTP/1.1 200 OK

Hello World

CIが動くたびに、ケースのtest/t/cases/guides.rbがこのリクエストを送ります。ケースは、ステータス行、ここに載せたヘッダ、ボディ全体を比べます。5個のファイルを最後に変えたのは、2026-10-29のコミット32219e53です。

「はじめに」のページでは、同じ種類のハンドラをDockerで動かします。

リバースプロキシ

スクリプトが、リクエストごとにproxy_passのバックエンドを選びます。サンプルは、ガイドのバックエンドへリクエストを振り分けるにあります。

ファイルによるアクセスリスト

accessハンドラは、ファイルに載ったクライアントに403を返します。サンプルは、ガイドのファイルに載せたクライアントを拒否するにあります。

MarkdownをHTMLに変換する出力フィルタ

ボディフィルタが、.mdのファイルのボディをHTMLに変換します。フィルタの部分は、ガイドのレスポンスのボディを変えるのサンプルです。そのサンプルは、テキストファイルをHTMLのページで包みます。

テストしていません。Markdownの変換には、gemのmruby-discountが要ります。build_config.rbではmruby-discountの行がコメントになっていて、このgemはビルドに入りません。このgemをビルドするCIのジョブもありません。試すには、build_config.rbのmruby-discountの行のコメントを外し、ビルドし直してください。

location ~ \.md$ {
    mruby_output_body_filter /path/to/filter.rb cache;
}

# /path/to/filter.rb
f = Nginx::Filter.new

css = "/css/markdown.css"   # a stylesheet that your server serves
md = Discount.new css, "markdown"

f.body = md.md2html f.body

Redisでメンテナンスモードに切り替える

accessハンドラが、Redisからフラグを読み、フラグが立っている間は503を返します。フラグが立っていなければ、nginxがリクエストをプロキシします。この例は、takeswimによる日本語の記事を元にしています。

テストしていません。CIのテストのジョブはRedisのサーバを動かさないので、この例を実行するサンプルはありません。デフォルトのビルドは、この例が使うRedisのクラスを持つgemのmruby-redisを含みます。

location / {
    mruby_access_handler_code '
        redis = Redis.new "127.0.0.1", 6379
        maintenance = redis.get("maintenance") == "on"
        redis.close
        Nginx.return Nginx::HTTP_SERVICE_UNAVAILABLE if maintenance
    ';
    proxy_pass http://127.0.0.1:8080;
}

mruby-redisは、Redisのサーバの応答をワーカーの中で1つずつ待つので、その間ワーカーはほかのリクエストを処理しません。

Markdownのウェブページ

このcontentハンドラは、MarkdownのテキストをHTMLのページに変換します。

テストしていません。gemのmruby-discountが要ります。build_config.rbではmruby-discountの行がコメントになっていて、このgemはビルドに入りません。このgemをビルドするCIのジョブもありません。試すには、mruby-discountの行のコメントを外し、ビルドし直してください。

location ~ \.rb$ {
    mruby_add_handler on;
}

# md.rb, under the root of the location
r = Nginx::Request.new
r.content_type = "text/html"

md = Discount.new "/css/markdown.css", "md test"

body = <<DATA
# Section

- item 1
- item 2
DATA

Nginx.echo md.header + body.to_html + md.footer

Dropboxのリンクのようなファイルサーバ

rewriteハンドラは、リクエストのパスをRedisで探し、リンクの期限が切れるまでそのファイルへリダイレクトします。

テストしていません。CIのテストのジョブはRedisのサーバを動かさないので、このユースケースを実行するサンプルはありません。デフォルトのビルドは、gemのmruby-redisを含んでいます。

location /dropbox {
    mruby_rewrite_handler /path/to/dropbox.rb;
}

# /path/to/dropbox.rb
redis = Redis.new "127.0.0.1", 6379
r = Nginx::Request.new
file = redis.hget r.uri, "file"
expire = redis.hget r.uri, "expire"
redis.close

if file && expire.to_i >= Time.now.to_i
  Nginx.redirect file
else
  Nginx.return Nginx::DECLINED
end

リンクはRedisのハッシュです。たとえばredis-cliでこう作ります。

HSET /dropbox/aaabbbcccddd file /files/hoge.html
HSET /dropbox/aaabbbcccddd expire 1900000000

記事とほかの例

日本語の記事のDynamic Image Provider
ロシア語の記事のResearch ngx_mruby and use output filter
Let’s Encryptを使ったACMEのauto ssl(ngx_mruby 2.x)：auto-sslのmrbgemと、動いているRedisのサーバが要ります。ngx_mruby 3.0.0にはこのgemがありません。詳しくはauto-sslのmrbgemと、それと一緒に入っていたクラスにあります。この例のACMEのクライアントはACMEv1を使いますが、Let’s EncryptはもうACMEv1を提供していません。