エンジニアのソフトウェア的愛情

または私は如何にして心配するのを止めてプログラムを・愛する・ようになったか

C++ による NIF ことはじめ

使い慣れている言語が C++ なので、ここでは C++ で説明しますが基本的に C 言語でも同じように記述できるはずです。 というか、世の中の NIF の説明は圧倒的に C 言語が多い。

詳細の解説は置いておいて。コードを書いてから呼び出せるところまでを順にたどってゆきます。

(不備など発見されましたらご指摘いただけると幸いです)

C++ のコードを用意する

二つの整数の和を返す add(int, int) を定義し、これを Elixir から呼び出すインタフェースを書きます。

#include <erl_nif.h>

int add(int x1, int x2) {
  return x1 + x2;
}

ERL_NIF_TERM add_nif(ErlNifEnv* env, int argc, const ERL_NIF_TERM argv[]) {
  int x1;
  int x2;

  if (!enif_get_int(env, argv[0], &x1)) {
    return enif_make_badarg(env);
  }

  if (!enif_get_int(env, argv[1], &x2)) {
    return enif_make_badarg(env);
  }

  int result = add(x1, x2);

  return enif_make_int(env, result);
}

ErlNifFunc nif_funcs[] = {
  {"add", 2, add_nif}
};

ERL_NIF_INIT(Elixir.Calc, nif_funcs, nullptr, nullptr, nullptr, nullptr);

add_nif が Elixir とインタフェースする関数です。 Elixir から呼び出される関数の型はこの形で定義します。

enif_get_int で引数を整数型として値を取得します。

戻り値は、演算結果を enif_make_int で Elixir の整数としての値を構築して返します。 また引数エラーの場合は enif_make_badarg で例外を構築して返します。

ERL_NIF_INIT で初期化を定義します。

# 説明
1 モジュール名を指定します。Elixir のモジュール名は VM 上では Elixir. という接頭辞つきで扱われます。ここではその接頭辞つきの名前で指定します。
2 関数の定義の配列を指定します。個々の定義は、Elixir での関数名, 関数のアリティ, C++ の関数のポインタ の配列からなります。
3 ライブラリがロードされたときに呼び出される関数を指定します。
4 OTP 20 以降利用されなくなりました。
5 モジュールのアップグレイドが発生したときに呼び出される関数を指定します。
6 ライブラリがアンロードされたときに呼び出される関数を指定します。

詳しくはドキュメントを参照してください。

C++ のコードをコンパイルする

コードをコンパイルする前に。erl_nif.h のパスを確認します。

ヘッダファイルは :code.root_dir/0 で取得できるパスの下、 usr/include に配置されています。

$ ls $(elixir -e 'IO.puts(:code.root_dir())')/usr/include
driver_int.h
ei.h
ei_connect.h
eicode.h
erl_driver.h
erl_drv_nif.h
erl_fixed_size_int_types.h
erl_int_sizes_config.h
erl_interface.h
erl_memory_trace_parser.h
erl_nif.h
erl_nif_api_funcs.h

コンパイルしたライブラリの配置について、はっきりとしたルールを見つけることができなかったのですが、種々のリソースを配置している priv に置くことにしました。

$ mkdir priv
$ g++ -I$(elixir -e 'IO.puts(:code.root_dir())')/usr/include \
      -fPIC \
      -shared \
      -undefined dynamic_lookup \
      -o priv/calc.so \
      c_src/calc.cpp

C++ で作成したライブラリを Elixir で読み込む

作成したライブラリを利用する Elixir 側のコードです。

ライブラリのロードは :erlang.load_nif/2 を利用します。 第 1 引数にはライブラリの拡張子を除いたパスを指定します。 第 2 引数にはライブラリに渡す値を指定します。 この値は ERL_NIF_INIT の第 3 引数に指定した関数に渡されます。

ライブラリを配置したディレクトリのパスは :code.priv_dir/1 で取得します。 この関数は _build ディレクトリの下にある priv の場所を返してくれます。 _build ディレクトリの下にある priv は通常はプロジェクト直下にある priv へのシンボリックリンクですが、リリース時には実際にディレクトリが作成され priv の内容がコピーされます。

開発時とリリース時で同じように参照できるので :code.priv_dir/1 を利用してライブラリをロードするようにしています。

またモジュールがロードされたときに自動的にライブラリをロードするように @on_load でモジュールのロードをフックし、そこでライブラリをロードしています。

defmodule Calc do
  @on_load :load_nifs

  def load_nifs do
    :code.priv_dir(:calc)
    |> Path.join("calc")
    |> :erlang.load_nif(0)
  end

  def add(_, _) do
    raise "NIF has not been loaded"
  end
end

ここまで準備ができればあとは Calc モジュールを Elixir で書いたモジュールと同じように利用することができます。

$ iex -S mix
iex(1)> Calc.add(111, 222)
333
iex(2)> Calc.add(1.1, 2.2) 
** (ArgumentError) argument error
    (calc) Calc.add(1.1, 2.2)

C++コンパイルを mix compile にまかせる

ここまで C++ のコードは Elixir のコードとは別にコンパイルしましたが、mix compile コマンドなどで Elixir のコードがコンパイルされるときに一緒にコンパイルされると便利です。 C++コンパイルを Elixir のコードで記述し、コンパイル時に実行するコードに含めることでそれを実現できます。

まず Mix.Tasks.Compile.Calc というモジュールを mix.exs の中で定義し、run/1 という関数を記述します。 その中で System.cmd/3 を利用して C++コンパイルを実行します。

次に project/0 で定義しているキーワードリストに compilers という項目を追加します。この値はデフォルトでは Mix.compilers/0 が返すリストの値になっていますが、今回記述したモジュールをこのリストに追加します。

defmodule Calc.MixProject do
  use Mix.Project

  def project do
    [
      # ...
      compilers: [:calc | Mix.compilers()]
    ]
  end

  # ...
end

defmodule Mix.Tasks.Compile.Calc do
  def run(_argv) do
    erl_path = Path.join(:code.root_dir(), "usr")
    include_path = Path.join(erl_path, "include")
    target_path = Path.join("priv", "calc.so")

    File.mkdir_p("priv")

    {result, _} =
      System.cmd(
        "g++",
        [
          "-I#{include_path}",
          "-fPIC",
          "-undefined", "dynamic_lookup",
          "-shared",
          "-o", target_path,
          "c_src/calc.cpp"
        ],
        stderr_to_stdout: true
      )

    IO.puts(result)
  end
end

これでライブラリが作成されていない状態からでも mix compileiex -S mix といった Elixir のコードがコンパイルされるのと合わせてライブラリの作成の実行されるようになりました。

コンパイルの手間を減らすパッケージを利用する

C++ のコードのコンパイルMakefile で管理することが多いと思いますが、Makefile を利用したコンパイルを手助けしてくれるパッケージが提供されています。

いつか読むはずっと読まない:数論は数学の女王

数の女王

数の女王

  • 作者:川添 愛
  • 出版社/メーカー: 東京書籍
  • 発売日: 2019/07/16
  • メディア: 単行本(ソフトカバー)

「黒のマティルデ」の数についてはこちらに詳しく書かれています。

Phoenixの認証をGuardianに護らせる

Phoenix で作成したアプリケーションに、権利のあるユーザにのみアクセスを許可したいばあいに Guardian という Elixir のパッケージを利用して実現する方法の覚書です。

基盤にしている JWT などの技術に今のところ明るくないこともあり、ここでは手順だけ記述します。

ドキュメントにも手順が書かれているのですが、記述が別れていたり微妙にわかりにくい部分があっりしたので自分で試したものを書き下してみました。

Phoenix app を用意する

認証機能を実装したい Phoenix app を用意します。

ここでは my_app という名で作成し、以降もこの名前で説明をしてゆきます。

$ mix phx.new my_app

アカウントを管理する仕組みを用意する

ユーザがアプリケーションにログインすることを想定して、認証されるアカウントを管理する仕組みを用意します。

実際にはユーザ情報をデータベースに格納するところですが、この記事では簡単に特定のユーザ名とパスワードの組を受け付ける仕組みで代用します。

lib/my_app/accounts/user.ex

ユーザデータを格納する構造体です。

defmodule MyApp.Accounts.User do
  defstruct [:username, :password]
end

lib/my_app/accounts.ex

ユーザ名とパスワードの組で認証するモジュールです。 実装はユーザ名、パスワードとも固定にしています。

defmodule MyApp.Accounts do
  alias MyApp.Accounts.User

  @username "foobar"
  @password "FooBar"

  @doc """
  usename をキーにユーザを取得する

  ユーザが存在する場合は、ユーザデータを返します。

  ユーザが存在しない場合は、 `nil` を返します。

  ## Example

      iex> MyApp.Accounts.get_user_by_username("foobar")
      %MyApp.Accounts.User{username: "foobar", password: "FooBar"}

      iex> MyApp.Accounts.get_user_by_username("hoge")
      nil
  """
  def get_user_by_username(username) do
    case username do
      @username -> %User{username: @username, password: @password}
      _ -> nil
    end
  end

  @doc """
  ユーザ名とパスワードで認証する

  認証に成功した場合は、 `:ok` とユーザデータのタプルを返します。

  認証に失敗した場合は、 `:error` と失敗理由のタプルを返します。

  ## Example

      iex> MyApp.Accounts.authenticate_user("foobar", "FooBar")
      {:ok, %MyApp.Accounts.User{username: "foobar", password: "FooBar"}}

      iex> MyApp.Accounts.authenticate_user("hoge", "Hoge")
      {:error, :unauthorized}
  """
  def authenticate_user(username, password) do
    case {username, password} do
      {@username, @password} -> {:ok, %User{username: @username, password: @password}}
      _ -> {:error, :unauthorized}
    end
  end
end

依存パッケージに Guardian を追加する

mix.exs ファイルを編集して deps/0 に記述される依存パッケージに Guardian を追加します。

mix hex.info コマンドで確認すると、この記事を書いた時点の最新バージョンは 2.0 でしたので、mix.exs でもこのバージョンを指定することにします。

$ mix hex.info guardian                                                                                                                                                      
Elixir Authentication framework                                                                                                                                                     
                                                                                                                                                                                    
Config: {:guardian, "~> 2.0"}                                                                                                                                                       
Releases: 2.0.0, 1.2.1, 1.2.0 (retired), 1.1.1, 1.1.0, 1.0.1, 1.0.0, 1.0.0-beta.1, ...                                                                                              
                                                                                                                                                                                    
Licenses: MIT                                                                                                                                                                       
Links:                                                                                                                                                                              
  Github: https://github.com/ueberauth/guardian  

mix.exs を編集して {:guardian, "~> 2.0"} の記述を追加します。

--- a/mix.exs
+++ b/mix.exs
@@ -38,7 +38,8 @@ defmodule MyApp.MixProject do
       {:phoenix_live_reload, "~> 1.2", only: :dev},
       {:gettext, "~> 0.11"},
       {:jason, "~> 1.0"},
-      {:plug_cowboy, "~> 2.0"}
+      {:plug_cowboy, "~> 2.0"},
+      {:guardian, "~> 2.0"}
     ]
   end
 end

パッケージを取得します。

 $ mix deps.get

Guardian モジュールを記述する

Guardian パッケージを利用したモジュールを 3 つ定義します。

パッケージのドキュメントにあるサンプルでは lib/my_app/ にモジュールを定義しているのですが、認証は Web サービスの領分と思うのでここでは lib/my_app_web/ に定義することにしました(この点、ご意見いただけるとさいわいです)。

lib/my_app_web/auth/
├── error_handler.ex
├── guardian.ex
└── pipeline.ex

lib/my_app_web/auth/guardian.ex

Guardian の実装です。

ここで resource はユーザデータに当たり、token はユーザ名 (username) に当たります。

defmodule MyAppWeb.Auth.Guardian do
  use Guardian, otp_app: :my_app

  alias MyApp.Accounts

  def subject_for_token(resouce, _claims) do
    {:ok, resouce.username}
  end

  def resource_from_claims(%{"sub" => username}) do
    case Accounts.get_user_by_username(username) do
      nil -> {:error, :resource_not_found}
      user -> {:ok, user}
    end
  end
end

lib/my_app_web/auth/error_handler.ex

認証に失敗したときに実行されるエラーハンドラです。 Guardian.Plug.ErrorHander を実装します。

defmodule MyAppWeb.Auth.ErrorHandler do
  @behaviour Guardian.Plug.ErrorHandler

  import Plug.Conn

  def auth_error(conn, {type, _reason}, _opts) do
    conn
    |> put_resp_content_type("text/plain")
    |> send_resp(401, to_string(type))
  end
end

lib/my_app_web/auth/pipeline.ex

上で実装したモジュールを使ってパイプラインを定義します。

defmodule MyAppWeb.Auth.Pipeline do
  use Guardian.Plug.Pipeline,
    otp_app: :my_app,
    error_handler: MyAppWeb.Auth.ErrorHandler,
    module: MyAppWeb.Auth.Guardian

  plug Guardian.Plug.VerifySession
  plug Guardian.Plug.VerifyHeader
  plug Guardian.Plug.LoadResource, allow_blank: true
end

router にパイプラインを追加する

lib/my_app_web/router.ex を編集してパイプラインを追加します。

  pipeline :auth do
    plug MyAppWeb.Auth.Pipeline
  end

  pipeline :ensure_auth do
    plug Guardian.Plug.EnsureAuthenticated
  end

セッションを管理する仕組みを用意する

ユーザ名とパスワードを入力するフォームと、入力された情報をハンドリングするコントローラを実装します。

lib/my_app_web/templates/session/new.html.eex

<%= form_for :user, Routes.session_path(@conn, :create), fn f -> %>

  <%= label f, :username %>
  <%= text_input f, :username %>

  <%= label f, :password %>
  <%= password_input f, :password %>

  <%= submit "login" %>
<% end %>

lib/my_app_web/views/session_view.ex

defmodule MyAppWeb.SessionView do
  use MyAppWeb, :view
end

lib/my_app_web/controllers/session_controller.ex

コントローラでは、入力されたユーザ名とパスワードを MyApp.Accounts.authenticate_user/2 で認証にかけます。

成功したばあい、Guardian.Plug.sign_in/5 でユーザのトークンをセッションに記憶します。 ユーザ情報からのトークンの抽出は、先に定義したモジュール MyAppWeb.Auth.Guardian の関数が利用されます。

トークンはログアウトの際の Guardian.Plug.sign_out/3 でセッションから削除されます。

defmodule MyAppWeb.SessionController do
  use MyAppWeb, :controller

  def new(conn, _) do
    conn
    |> render("new.html")
  end

  def create(conn, %{"user" => %{"username" => username, "password" => password}}) do
    case MyApp.Accounts.authenticate_user(username, password) do
      {:ok, user} ->
        conn
        |> put_flash(:info, "Welcome back!")
        |> Guardian.Plug.sign_in(MyAppWeb.Auth.Guardian, user)
        |> redirect(to: Routes.page_path(conn, :index))

      {:error, reason} ->
        conn
        |> put_flash(:error, to_string(reason))
        |> new(%{})
    end
  end

  def destroy(conn, _) do
    conn
    |> Guardian.Plug.sign_out(MyAppWeb.Auth.Guardian, [])
    |> redirect(to: Routes.session_path(conn, :new))
  end
end

routing を設定する

ルーティングに先ほど定義したパイプラインを設定していきます。

アプリケーションを作成した時点ではルーティングはこのようになっています。

   scope "/", MyAppWeb do
    pipe_through :browser
 
     get "/", PageController, :index
   end

これを次のように変更します。

  scope "/", MyAppWeb do
    pipe_through [:browser, :auth]

    get "/login", SessionController, :new
    post "/session", SessionController, :create
  end

  scope "/", MyAppWeb do
    pipe_through [:browser, :auth, :ensure_auth]

    get "/", PageController, :index
    delete "/session", SessionController, :destroy
  end

これでパイプラインの :ensure_auth を利用するスコープは認証がすんでいないとアクセスすることができなくなりました。

config を設定する

Guardian の設定として、アプリケーションと秘密鍵を config で設定します。 ここでは秘密鍵環境変数から取得するようにしています。

config :my_app, MyAppWeb.Auth.Guardian,
  issuer: "my_app",
  secret_key: System.get_env("GUARDIAN_SECRET_KEY")

mix guardian.gen.secret を利用して秘密鍵を生成し、環境変数に設定します。

$ export GUARDIAN_SECRET_KEY=`mix guardian.gen.secret`

護られていることを確認する

アプリケーションを起動します。

$ mix phx.server

この状態で http://localhost:4000 にアクセスすると、認証がすんでいないので unauthenticated と表示されます。

次にログインしてみます。

http://localhost:4000/login にアクセスします。 フォームが表示されるので用意しておいたユーザ名とパスワード foobarFooBar を入力します。 入力が正しければ先ほど拒否されていた http://localhost:4000 にリダイレクトされ Welcome back! の文字が表示されるはずです。

ログアウトする

ログアウト機能を追加します。

lib/my_app_web/templates/layout/app.html.eex

lib/my_app_web/templates/layout/app.html.eex を開き、Get started と記述されている行の下にログアウトのリンクを作成します。

Guardinan.Plug.curent_resource/2 関数でログイン時のリソースが取得できます。 具体的には今回はユーザのレコードをリソースとしているのでこの関数でユーザのレコードを得ることができます。

これを利用してログインしているばあいだけログアウトのリンクを表示するようにします。

            <%= if Guardian.Plug.current_resource(@conn) do %>
              <li><%= link "logout", to: Routes.session_path(@conn, :destroy), method: :delete %></li>
            <% end %>

ログインを促す

認証前に認証が必要なページにアクセスしたばあい今は unauthenticated と表示するだけですが、これをログインページにリダイレクトするようにします。

Guardian.Plug.ErrorHandler.auth_error/3 を次のように変更します。 フラッシュにメッセージを設定する関数 put_flash/3 とリダイレクトの関数 redirect/2 の二つを利用していますが、扱いやすくするため定義されているモジュール Phoenix.Controller を import して利用しています。

defmodule MyAppWeb.Auth.ErrorHandler do
  @behaviour Guardian.Plug.ErrorHandler

  import Plug.Conn

  import Phoenix.Controller, only: [put_flash: 3, redirect: 2]
  alias MyAppWeb.Router.Helpers, as: Routes

  def auth_error(conn, {type, _reason}, _opts) do
    conn
    |> put_flash(:error, "unauthorized")
    |> redirect(to: Routes.session_path(conn, :new))
  end
end

これでログインしてない状態で http://localhost:4000 にアクセスしたとき、ログインページにリダイレクトされるようになりました。

いつか読むはずっと読まない:習慣の集まり

メリットの法則 行動分析学・実践編 (集英社新書)

メリットの法則 行動分析学・実践編 (集英社新書)

黒魔術で Elixir に Ruby を召喚する

まず始めに。

ネタ記事です。

ひさびさのネタ記事です。

ネタプログラミングです。

とはいえ。

黒魔術を使うことはなくても、このようなしくみを知っていると、その知識が役に立つときが来るかもしれません(来ないかもしれません)。

Level 1, Medium: Port.open/2 で Ruby を起動する

まずは定石の範囲で。

Port.open/2 を使って Ruby のプロセスを起動します。

外部プロセスの起動には System.cmd/3 という関数もありますが、 Port.open/2 の方が制御を細かくできるのでこちらを利用しすることにします。 ちなみに System.cmd/3 も内部では Port.open/2 を利用していました。

path = System.find_executable("ruby")
port = Port.open({:spawn_executable, path},
         [:binary, args: ["-e", "puts('Hello')"]])

receive do
  {^port, {:data, data}} -> data
end
# => "Hello\n"

Port.open/2 でプロセスを起動すると、そのプロセスの出力をメッセージで送信します。 メッセージはポートの値とデータのタプル、データは :data とデータ本体の値のタプル、という形式になっています。

メッセージの形式の詳細はドキュメントを参照してください。

Port.open/2 の戻り値を送り先に指定すると、起動したプロセスにメッセージを送ることができます。

path = System.find_executable("ruby")

# 1 行読み込んで 1 行出力する
port = Port.open({:spawn_executable, path}, [:binary, args: ["-e", ~S|puts("Hello #{gets.strip}!")|]])

# 1 行分の文字列を送る
send(port, {self(), {:command, "world\n"}})

receive do
  {^port, {:data, data}} -> data
end
# => "Hello world!\n"

Level 2, Seer: irb を起動して対話的に式を評価する

ruby コマンドでは、ループ処理を自分で描かない限り、ワンショットの実行になってしまいます。 そこで代わりに irb を起動して一つのプロセスで何度でも式を評価できるようにしてみます。

path = System.find_executable("irb")
port = Port.open({:spawn_executable, path}, [:binary])

ここで。irb を起動しするとどのような挙動になるか IEx で flush/0 を使って確認してみます。

iex> path = System.find_executable("irb")
iex> port = Port.open({:spawn_executable, path}, [:binary])
#Port<0.5>

iex> flush
{#Port<0.5>, {:data, "Switch to inspect mode.\n"}}

起動しただけでなにやらメッセージを受信しています。

メッセージとして Ruby の式を送ってみます。 評価は行単位で行われるので末尾の改行( "\n" )を忘れないようにしてください。

# 式展開で書くと Elixir の文脈で展開してしまうので文字列連結 ++ で書いています
iex> send(port, {self(), {:command, "puts('Hello ' ++ (gets.strip) ++ '!')\n"}})

# gets が読み込む文字列を送る
iex> send(port, {self(), {:command, "world\n"}})
{#PID<0.108.0>, {:command, "world\n"}}

iex> flush
{#Port<0.5>, {:data, "puts('Hello ' ++ (gets.strip) ++ '!')\n"}}
{#Port<0.5>, {:data, "Hello world!\n"}}
{#Port<0.5>, {:data, "nil\n"}}

入力した評価対象の文字列( "puts('Hello ' ++ (gets.strip) ++ '!')\n" )と、puts の出力結果、そして puts の戻り値の値である nil が送り返されました。

出力した内容( "Hello irb!\n" )だけが得られればよいのですが、入力した評価対象の内容も送られてきてしまっています。

明示的に出力した内容以外の出力を抑制するオプションをつけて irb を起動するようにします。

iex> path = System.find_executable("irb")
# 評価する式の出力を抑える --noverbose と 評価した値の出力を抑える --noecho を指定する
iex> port = Port.open({:spawn_executable, path}, [:binary, args: ["--noverbose", "--noecho"]])

iex> send(port, {self(), {:command, "puts('Hello ' ++ (gets.strip) ++ '!')\n"}})
iex> send(port, {self(), {:command, "world\n"}})

iex> flush
{#Port<0.5>, {:data, "Hello world!\n"}}

これで評価する式と評価した値、加えて起動時のメッセージの出力を抑制することができました。

Level 3, Conjuror: サーバにする

これらを踏まえて。 Ruby の式を評価して結果を返すサーバを書いてみます。

defmodule ExIRB do
  use GenServer

  @name __MODULE__

  def start_link(opts) do
    name = Keyword.get(opts, :name, @name)
    GenServer.start_link(__MODULE__, opts, name: name)
  end

  def eva_ruby(server \\ @name, expression) do
    GenServer.call(server, {:eva_ruby, expression})
  end

  def init(_opts) do
    path = System.find_executable("irb")
    port = Port.open({:spawn_executable, path}, [:binary, args: ["--noverbose", "--noecho"]])

    {:ok, %{port: port, froms: []}}
  end

  def handle_call({:eva_ruby, expression}, from, %{port: port, froms: froms} = state) do
    send(port, {self(), {:command, expression}})

    {:noreply, %{state | froms: [from | froms]}}
  end

  def handle_info({port, {:data, data}}, %{port: port, froms: [from | froms]} = state) do
    GenServer.reply(from, data)

    {:noreply, %{state | froms: froms}}
  end
end

実行。

iex> ExIRB.start_link([])
iex> ExIRB.eva_ruby("puts('Hello ExIRB!')\n")
"Hello ExIRB!\n"

ここで注意点として。この実装では式を評価したら必ずメッセージが返されることを期待しています。 値を出力しない式を与えるとタイムアウトが発生します。

値が返ることを期待しない式を評価したい場合は、次のような関数とハンドラを追加することで実現できます。

  def cast_ruby(server \\ @name, expression) do
    GenServer.cast(server, {:cast_ruby, expression})
  end
  def handle_cast({:cast_ruby, expression}, %{port: port} = state) do
    send(port, {self(), {:command, expression}})

    {:noreply, state}
  end
# irb は gets の入力待ちになる
iex> ExIRB.cast_ruby("puts('Hello ' ++ (gets.strip) ++ '!')\n")

# 文字列を送ると gets が値を返し、結果として上の式が評価された値が返される
iex> ExIRB.eva_ruby("world\n")
"Hello world!\n"

ここで puts を使っていると末尾に改行コードが付いてしまいます。 これは print に変更することでこれを回避できます。

iex> ExIRB.eva_ruby("print('Hello ExIRB!')\n")                
"Hello ExIRB!"

Level 4, Magician: マーシャリングした値を利用する

irb のプロセスを起動し評価したい Ruby の式を渡すことで値を得ることができるようになりました。 しかし文字列という形式でしかやりとりができません。 その文字列を Elixir 上でパースすることもできますが面倒です。

シリアライズした Ruby の値を Elixir でデシリアライズできれば文字列をパースするよりもミスなく値を受け渡すことができるはずです。

と、いうわけで。

Ruby の値を Marshal で出力し、それを Elixir で読み込むことにします。

Format of marshaling

フォーマットの仕様はドキュメントにまとめられています。

フォーマットのバージョンは Ruby 1.8.0 以降は 4.8 なので、先頭の 2 バイトは 0x040x08 です。

niltruefalse はそれぞれ "0""T", "F" という形式になるので、マーシャリングされると

Ruby の値 マーシャリングされた値
nil "\x04\x080"
true "\x04\x08T"
false "\x04\x08F"

irb で確認してみます。

irb> Marshal.load("\x04\x080")
=> nil
irb> Marshal.load("\x04\x08T")
=> true
irb> Marshal.load("\x04\x08F")
=> false

Level 3 で作成した ExIRB で同じように評価してみます。

iex> ExIRB.eva_ruby("print(Marshal.dump(nil))\n")
<<4, 8, 48>>
iex> ExIRB.eva_ruby("print(Marshal.dump(true))\n")
<<4, 8, 84>>
iex> ExIRB.eva_ruby("print(Marshal.dump(false))\n")
<<4, 8, 70>>

文字として表示できない値が含まれるためバイト列として表示されます。 フォーマットが規定されているバイト列のパースは文字列のパースよりも容易ですし、なにより Elixir はバイト列のパースが得意です。

そんなわけで。

マーシャリングされた Ruby の値を Elixir の値に変換するパッケージを がっ! と書いてみました。

mix.exsdepsex_marshal を追加します。

# mix.exs

  defp deps do
    [
      {:ex_marshal, github: "mattsan/ex_marshal"}
    ]
  end

iex を起動しなおし、マーシャリングした値を ExMarshal.load/1 で読み込んでみます。

iex> ExIRB.start_link([])
iex> ExIRB.eva_ruby("print(Marshal.dump(nil))\n") |> ExMarshal.load()
nil
iex> ExIRB.eva_ruby("print(Marshal.dump(false))\n") |> ExMarshal.load()
false
iex> ExIRB.eva_ruby("print(Marshal.dump(true))\n") |> ExMarshal.load()
true
iex> ExIRB.eva_ruby("print(Marshal.dump(123))\n") |> ExMarshal.load()
123
iex> ExIRB.eva_ruby("print(Marshal.dump([1,2,3]))\n") |> ExMarshal.load()
[1, 2, 3]
iex> ExIRB.eva_ruby("print(Marshal.dump({a: 1, b: '2', c: :three}))\n") |> ExMarshal.load()
%{a: 1, b: "2", c: :three}

扱える値はドキュメント( lib/ex_marshal.ex の moduledoc )を参照してください。

Ruby のコードを外部の関数として扱うと割り切ればマーシャリングの処理をハンドラの中に隠すことができます。 思い切って書き換えてみます。

  def handle_call({:eva_ruby, expression}, from, %{port: port, froms: froms} = state) do
    send(port, {self(), {:command, "print(Marshal.dump(#{expression}))\n"}})

    {:noreply, %{state | froms: [from | froms]}}
  end

  def handle_info({port, {:data, data}}, %{port: port, froms: [from | froms]} = state) do
    GenServer.reply(from, ExMarshal.load(data))

    {:noreply, %{state | froms: froms}}
  end

修正したコードの内容を反映して Ruby の式を評価してみます。

iex> ExIRB.eva_ruby("nil")
nil
iex> ExIRB.eva_ruby("true")
true
iex> ExIRB.eva_ruby("true")
true
iex> ExIRB.eva_ruby("false")
false
iex> ExIRB.eva_ruby("123")
123
iex> ExIRB.eva_ruby("[1,2,3]")
[1, 2, 3]
iex> ExIRB.eva_ruby("{a: 1, b: '2', c: :three}")
%{a: 1, b: "2", c: :three}

文字列の中は Ruby の式として評価されるのでメソッドも記述できます。 結果は ExMarshal.load/1 で変換しているので Elixir の値として返されます。

iex> ExIRB.eva_ruby("(1..10).map {|i| i * i }")
[1, 4, 9, 16, 25, 36, 49, 64, 81, 100]

Level 5, Enchanter: ライブラリを読み込む

irbコマンドラインオプション -r で起動時にライブラリを読み込むことができます。

ここでは ExIRB.start_link/1 の引数で指定できるようにしてみます。

ExIRB.init/1 を次のように書き換えます。

  def init(opts) do
    path = System.find_executable("irb")
    requires =
      opts
      |> Keyword.get(:require, [])
      |> Enum.map(&"-r#{&1}")
    port = Port.open({:spawn_executable, path}, [:binary, args: ["--noverbose", "--noecho" | requires]])

    {:ok, %{port: port, froms: []}}
  end

オプションで :require で指定された値をライブラリ名のリストとして -r をつけて irb のオプションの形式にします。 Port.open/2 の起動時の引数にそれらを渡します。

ExIRB.start_link/1 でライブラリを指定します。

iex> ExIRB.start_link(require: ["yaml"])

ここでは yaml を指定しています。 これで YAML のメソッドを利用することができるようになりました。

iex> ExIRB.eva_ruby("YAML.load('---\n- 1\n- 2\n')")
[1, 2]

混乱しそうですが、こんなこともできます。

iex> yaml = """
...> ---
...> - 1
...> - 2
...> - a:
...>   - 3
...>   - 4
...> """
"---\n- 1\n- 2\n- a:\n  - 3\n  - 4\n"
iex> ExIRB.eva_ruby("YAML.load('#{yaml}')")
[1, 2, %{"a" => [3, 4]}]

Level 6, Warlock: apply(module, function, arguments)

Ruby の式を文字列で記述する代わりにモジュール名とメソッド名と引数列を評価できれば Elixir の値を渡すことができます。 ちょうど Kernel.apply/3 のような記述です。

このためにはまず引数列を文字列に変換する必要がありますが、これは個々の値を Kernel.inspect/2 で評価してコンマで連結すれば良さそうです。

iex> args = [1, "2", :three] |> Enum.map(&inspect/1) |> Enum.join(",")
"1,\"2\",:three"

iex> "Foo.bar(#{args})"
"Foo.bar(1,\"2\",:three)"

よさそうなのですが、いくつか落とし穴があるので注意しなければなりません。

長い値は省略される

要素の数が多く表現が長くなるばあい、途中から省略されてしまいます。

iex> (1..55) |> Enum.to_list() |> inspect()
"[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, ...]"

すべての要素を表示させるためには :limit オプションに :infinity を指定します。

iex> (1..55) |> Enum.to_list() |> inspect(limit: :infinity)
"[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55]"

表示できる文字コードのリストは charlist として表示される

Erlang や Elixir の「クセ」の部分。 整数値のリストなのに、その整数値が文字コードとして表示できるばあい、文字のリスト (charlist) として表現されてしまいます。

iex> (65..90) |> Enum.to_list() |> inspect(limit: :infinity)
"'ABCDEFGHIJKLMNOPQRSTUVWXYZ'"

整数値のリストとして表示させるためには :charlists オプションに false を指定します。

iex> (65..90) |> Enum.to_list() |> inspect(limit: :infinity, charlists: false)
"[65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90]"

マップはには % が付く

マップを inspect すると、%{} で囲まれた文字列になります。 これは Elixir の仕様ですから、もうどうしようもありません。

iex> %{a: 1} |> inspect(limit: :infinity, charlits: false)
"%{a: 1}"

…と、あきらめかけていたのですが。 バージョン 1.9.0 から :inspect_fun オプションに適切な変換を行う関数を渡すことで任意の表示をさせることができるようになりました。

たとえば次のような関数 MapToHash.inspect_fun/2 を用意します。

defmodule MapToHash do
  import Inspect.Algebra

  def inspect_fun(term, opts) when is_map(term) do
    arrow = string("=>")
    comma = string(",")

    docs =
      term
      |> Enum.reduce([string("}")], fn {k, v}, acc ->
        key = inspect_fun(k, opts)
        value = inspect_fun(v, opts)
        [comma, key, arrow, value | acc]
      end)

    docs =
      case docs do
        [^comma | docs] -> docs
        docs -> docs
      end

    concat([string("{") | docs])
  end

  def inspect_fun(term, opts) do
    Inspect.inspect(term, opts)
  end
end

この関数を :inspect_fun オプションに指定します。

iex> inspect(%{a: 1}, limit: :infinity, charlists: false, inspect_fun: &MapToHash.inspect_fun/2)
"{:a=>1}"

入れ子になったマップでも空のマップでも Ruby のハッシュの形式の文字列で出力できます。

iex> inspect(%{a: 1, b: %{c: %{d: :e}}}, limit: :infinity, charlists: false, inspect_fun: &MapToHash.inspect_fun/2)
"{:b=>{:c=>{:d=>:e}},:a=>1}"
iex> inspect(%{}, limit: :infinity, charlists: false, inspect_fun: &MapToHash.inspect_fun/2)
"{}"

Elixir のモジュール名には Elixir が付いている

あとはモジュール名と関数名とを連結して先に書いた関数で Ruby にメッセージを送ればよさそうです。

まず期待する文字列を組み立てられるか、次のような関数を書いて確かめてみます。

  def apply(module, function, args) do
    args_str =
      args
      |> Enum.map(fn arg ->
        arg
        |> inspect(limit: :infinity, charlists: false, inspect_fun: &MapToHash.inspect_fun/2)
      end)
      |> Enum.join(",")

    "#{module}.#{function}(#{args_str})"
  end

モジュール名と関数名を文字列で指定してみます。

iex> ExIRB.apply("YAML", "load", ["---\n- 1\n - 2\n"])
"YAML.load(\"---\\n- 1\\n - 2\\n\")"

よさそうです。

次に関数名をアトムで指定してみます。

iex> ExIRB.apply("YAML", :load, ["---\n- 1\n - 2\n"])
"YAML.load(\"---\\n- 1\\n - 2\\n\")"

これもよさそうです。

最後に kernel.apply/3 と同じようにモジュール名で指定してみます。

iex> ExIRB.apply(YAML, :load, ["---\n- 1\n - 2\n"])
"Elixir.YAML.load(\"---\\n- 1\\n - 2\\n\")"

Elixir の文字列がつきました。

Elixir のモジュール名の実態はアトムです。

iex> is_atom(YAML)
true

ですのでモジュールが定義されていなくてもモジュール名は自由に使うことができます。 ただし注意する点がああります。たとえば YAML と書いたばあい内部的には :"Elixir.YAML" という値になっているという点です。 これは IEx でも簡単に確認することができます。

iex> :"Elixir.YAML"
YAML

iex> :"Elixir.YAML" == YAML
true

モジュールは Module.split/1 を使うと安全に文字列として分割できるので今回はこれを使うことにします。

iex> [module_name] = Module.split(YAML)
["YAML"]
iex> module_name
"YAML"

上に書いた apply 関数を修正して、組み立てた文字列を Ruby で評価する関数にします。

  def apply(server \\ @name, module, function, args) do
    [module_name] = Module.split(module)
    args_str =
      args
      |> Enum.map(fn arg ->
        arg
        |> inspect(limit: :infinity, charlists: false, inspect_fun: &MapToHash.inspect_fun/2)
      end)
      |> Enum.join(",")

    GenServer.call(server, {:eval_ruby, "#{module_name}.#{function}(#{args_str})"})
  end
iex> ExIRB.start_link(require: ["yaml"])
iex> ExIRB.apply(YAML, :load, ["---\n- 1\n- 2\n"])
[1, 2]
iex> ExIRB.apply(YAML, :dump, [%{a: 1}])
"---\n:a: 1\n"

これで Kernel.apply/3 と同じ書式で Ruby のメソッドを呼び出せるようになりました。

Level 7, Sorcerer: 関数を定義する

apply できるようになりましたが、やはり本来の関数名で呼び出したいものです。

関数を定義してみましょう。

defmodule ExYAML do
  def load(str), do: ExIRB.apply(YAML, :load, [str])
  def dump(term), do: ExIRB.apply(YAML, :dump, [term])
end
iex> ExIRB.start_link(require: ["yaml"])
iex> ExYAML.dump(%{a: 1})
"---\n:a: 1\n"
iex(3)> ExYAML.load("---\n- 1\n- 2\n")
[1, 2]

呼び出しは便利になりましたが関数を定義するのが面倒です。

そんなときは。 そう、マクロです。

関数を定義するマクロを定義します。

defmodule Importer do
  defmacro import_ruby(module, function) do
    quote do
      def unquote(function)(args) do
        ExIRB.apply(unquote(module), unquote(function), args)
      end
    end
  end
end

関数を定義したいモジュールでマクロを展開します。

defmodule ExYAML do
  require Importer
  import Importer

  import_ruby YAML, :load
  import_ruby YAML, :dump
end

これだけで関数が使えるようになります。

iex> ExIRB.start_link(require: ["yaml"])
iex> ExYAML.dump([%{a: 1}])
"---\n:a: 1\n"
iex(3)> ExYAML.load(["---\n- 1\n- 2\n"])
[1, 2]

しかし。このままでは一つの引数しか受け取れないので複数の引数を渡したいときにはリストにまとめて渡す必要があります。

引数の数も定義できる方法を考えます。

まず、quote された関数の構造を調べます。

iex> quote do
...>   def dump(term, opts) do
...>     ExIRB.apply(YAML, :dump, [term, opts])
...>   end
...> end
{:def, [context: Elixir, import: Kernel],
 [
   {:dump, [context: Elixir], [{:term, [], Elixir}, {:opts, [], Elixir}]},
   [
     do: {{:., [], [{:__aliases__, [alias: false], [:ExIRB]}, :apply]}, [],
      [
        {:__aliases__, [alias: false], [:YAML]},
        :dump,
        [{:term, [], Elixir}, {:opts, [], Elixir}]
      ]}
   ]
 ]}

二つの引数 (term, opts) は、[{:term, [], Elixir}, {:opts, [], Elixir}] という構造に展開されていることがわかります。 また ExIRB.apply/3 の三つ目の引数 [term, opts] も同じ構造になっています。

つまり必要な引数の数だけこの構造を並べたものをマクロの値として返すようにすれば、欲しい引数の数の関数を得ることができるはずです。

引数の構造を組み立てます。 26 個より多い引数を持つ関数はないだろうという大雑把な考えのもと、Stream で個々の引数のタプルを組み立て Enum.take/2 で切り出します。

args =
  (?a..?z)
  |> Stream.map(&{String.to_atom(<<&1>>), [], __MODULE__})
  |> Enum.take(arity)

これを関数の定義に組み込みます。 全体では、このようになります。

defmodule Importer do
  defmacro import_ruby(module, function, arity) do
    args =
      (?a..?z)
      |> Stream.map(&{String.to_atom(<<&1>>), [], __MODULE__})
      |> Enum.take(arity)

    {
      :def, [context: __MODULE__, import: Kernel],
      [
        {
          function,
          [context: __MODULE__],
          args
        },
        [do: {
          {:., [], [ExIRB, :apply]},
          [],
          [
            module,
            function,
            args
          ]
        }]
      ]
    }
  end
end

マクロを展開します。 追加した第三引数に引数の個数を指定する必要がありますが、これを利用することで引数の個数違いの関数を定義することができるようになりました。

defmodule ExYAML do
  require Importer
  import Importer

  import_ruby YAML, :load, 1
  import_ruby YAML, :dump, 1
  import_ruby YAML, :dump, 2
end
iex> ExIRB.start_link(require: ["yaml"])
iex> ExYAML.dump([1, [2, [3, 4]]])
"---\n- 1\n- - 2\n  - - 3\n    - 4\n"
iex> ExYAML.dump([1, [2, [3, 4]]], %{indentation: 4})
"---\n- 1\n-   - 2\n    -   - 3\n        - 4\n"

これで扱いやすくなりました。

しかしまだ何度も import_ruby YAML と書かなければならない手間があります。

Kernel.SpecialForms.import/2 のように、関数名と引数の個数をペアにしたキーワードリストでまとめて定義できるようにしてみます。

マクロを修正します。

defmodule Importer do
  defmacro import_ruby(module, functions) do
    functions
    |> Enum.map(fn {function, arity} ->
      args =
        (?a..?z)
        |> Stream.map(&{String.to_atom(<<&1>>), [], __MODULE__})
        |> Enum.take(arity)

      {
        :def, [context: __MODULE__, import: Kernel],
        [
          {
            function,
            [context: __MODULE__],
            args
          },
          [do: {
            {:., [], [ExIRB, :apply]},
            [],
            [
              module,
              function,
              args
            ]
          }]
        ]
      }
    end)
  end
end

利用する側も修正します。

defmodule ExYAML do
  require Importer
  import Importer

  import_ruby YAML, load: 1, dump: 1, dump: 2
end

利用しやすくなりました。

Level 8, Necromancer: モジュールを定義する

しかしまだ問題があります。

defmodule ExYAMLandJSON do
  require Importer
  import Importer

  import_ruby YAML, load: 1, dump: 1
  import_ruby JSON, load: 1, dump: 1
end

同じ名前、同じ引数の数の関数を定義すると、先に定義した関数にすべてのパタンがマッチしてしまい後から定義した関数は呼ばれません。

iex> ExYAMLandJSON.dump(%{a: 1})
"---\n:a: 1\n"

名前空間をわけたいところです。 Ruby のモジュール名を渡しているので、これを名前空間にできないか考えます。

こんどは quote されたモジュールの構造を調べます。

iex> quote do
...>   defmodule Yaml do
...>     def dump(term) do
...>       ExIRB.apply(YAML, :dump, [term])
...>     end
...>
...>     def load(str) do
...>       ExIRB.apply(YAML, :dump, [str])
...>     end
...>   end
...> end
{:defmodule, [context: Elixir, import: Kernel],
 [
   {:__aliases__, [alias: false], [:Yaml]},
   [
     do: {:__block__, [],
      [
        {:def, [context: Elixir, import: Kernel],
         [
           {:dump, [context: Elixir], [{:term, [], Elixir}]},
           [
             do: {{:., [], [{:__aliases__, [alias: false], [:ExIRB]}, :apply]},
              [],
              [
                {:__aliases__, [alias: false], [:YAML]},
                :dump,
                [{:term, [], Elixir}]
              ]}
           ]
         ]},
        {:def, [context: Elixir, import: Kernel],
         [
           {:load, [context: Elixir], [{:str, [], Elixir}]},
           [
             do: {{:., [], [{:__aliases__, [alias: false], [:ExIRB]}, :apply]},
              [],
              [
                {:__aliases__, [alias: false], [:YAML]},
                :dump,
                [{:str, [], Elixir}]
              ]}
           ]
         ]}
      ]}
   ]
 ]}

関数を定義するタプル {:def, ...} の部分を除くと思いの外シンプルです。

また、マクロを利用するモジュールの名前空間の中でモジュールを定義したいわけですが、そのモジュール名は Kernel.SpecialForms.__CALLER__/0 で取得することができます。

これらをすべて適用します。

defmodule Requirer do
  defmacro require_ruby(module, functions) do
    ruby_module =
      case module do
        {:__aliases__, _, [ruby_module]} -> ruby_module
        module -> module
      end

    quoted_functions =
      functions
      |> Enum.map(fn {function, arity} ->
        args =
          (?a..?z)
          |> Stream.map(&{String.to_atom(<<&1>>), [], __MODULE__})
          |> Enum.take(arity)

        {
          :def, [import: Kernel],
          [
            {function, [], args},
            [do: {
              {:., [], [ExIRB, :apply]},
              [],
              [module, function, args]
            }]
          ]
        }
      end)

    {
      :defmodule,
      [import: Kernel],
      [
        Module.concat(__CALLER__.module, ruby_module),
        [do: {:__block__, [], quoted_functions}]
      ]
    }
  end
end

マクロを利用するモジュールを書きます。

defmodule ExYAMLandJSON do
  require Requirer
  import Requirer

  require_ruby YAML, load: 1, dump: 1
  require_ruby JSON, load: 1, dump: 1
end

使ってみます。

iex> ExIRB.start_link(require: ["yaml", "json"])
iex> ExYAMLandJSON.JSON.dump(%{a: 1, b: [1, 2, 3]})
"{\"b\":[1,2,3],\"a\":1}"
iex> ExYAMLandJSON.YAML.dump(%{a: 1, b: [1, 2, 3]})
"---\n:b:\n- 1\n- 2\n- 3\n:a: 1\n"

マクロを利用するモジュールの名前に require_ruby したモジュールの名前を連結した新しいモジュールが定義され、その各々に関数が定義されました。

Level 9, Wizard: ぜんぶまとめると

これらのコードを整理して GitHub に push しました

使ってみましょう。

プロジェクトを作成する

新しいプロジェクトを作成します。プロセスを supervisor で管理したいので --sup オプションを指定します。

$ mix new sample --sup
$ cd sample

依存パッケージを設定する

mix.exs を編集して依存パッケージに ex_irb を指定します。

defmodule Sample.MixProject do
  use Mix.Project

  def project do
    [
      app: :sample,
      version: "0.1.0",
      elixir: "~> 1.9",
      start_permanent: Mix.env() == :prod,
      deps: deps()
    ]
  end

  def application do
    [
      extra_applications: [:logger],
      mod: {Sample.Application, []}
    ]
  end

  defp deps do
    [
      {:ex_irb, github: "mattsan/ex_irb"}
    ]
  end
end

パッケージを取得します。

$ mix deps.get

ExIRB プロセスの起動を設定する

lib/sample/application.ex を編集して ExIRB のプロセスを起動する設定を記述します。

defmodule Sample.Application do
  @moduledoc false

  use Application

  def start(_type, _args) do
    children = [
      {ExIRB, require: ["yaml", "json"]}
    ]

    opts = [strategy: :one_for_one, name: Sample.Supervisor]
    Supervisor.start_link(children, opts)
  end
end

召喚するモジュールを記述する

ExIRB.Requirer を使って Ruby のモジュールを Elixir のモジュールに召喚します。

defmodule Sample do
  @moduledoc """
  Documentation for Sample.
  """

  require ExIRB.Requirer
  import ExIRB.Requirer

  require_ruby YAML, load: 1, dump: 1, dump: 2
  require_ruby JSON, load: 1, dump: 1
end

使う

iex を起動します。

$ iex -S mix

iex のプロンプトから召喚した Ruby のメソッドを呼びます。 アプリケーションが起動するときに ExIRB を起動しているのですぐに利用することができます。

iex> Sample.JSON.dump(%{a: 1})
"{\"a\":1}"
iex> Sample.YAML.dump(%{a: 1})
"---\n:a: 1\n"
iex> Sample.JSON.load(~S[{"a":1}])
%{"a" => 1}
iex> Sample.YAML.load("---\na: 1\n")
%{"a" => 1}

ちなみに。

終了処理をきちんと書いていないので、 iex を終了すると irb と接続しているポートが閉じて irb が例外を投げスタックトレイスを吐き出して停止します。

まぁ、黒魔術だから…。

結論

わかりやすく書こう。

----うますぎるプログラムはいけない

プログラム書法 第2版

いつか読むはずっと読まない:霊媒師、占い師、奇術師、…

ダンジョンズ&ドラゴンズ スターター・セット第5版

ダンジョンズ&ドラゴンズ スターター・セット第5版

Phoenixが入ったDocker containerをHerokuに配備する

de・ploy | dɪplɔ́ɪ |

他動詞

1 〘軍〙 〈部隊など〉を展開させる, 〈兵器など〉を配置[配備]する.

ウィズダム英和辞典


いまさらなのですが。

Phoenix のドキュメントに Docker container を利用したリリースの手順が追加されていることに気がつきました。 今夏のアップデートで追加されたようです。

また Heroku のドキュメントにも Docker container を利用したデプロイの手順が掲載されています。

従来から Phoenix アプリケーションを Heroku にデプロイするには buildpack を利用する手順がドキュメントに記載されていますが、これらのドキュメントに従えば Docker container を利用したリリースが可能になるはずです。

と、いうわけで。 Phoenix アプリケーションを new するところから Heroku にデプロイするまでの手順をまとめてみました。

いずれも Phoenix あるいは Heroku のドキュメントに記載されている内容ですので難しいことはないと思いますが、細かなところで情報が分散していてつまづくところがあったので何かの参考になればと思います。

{:elixir, "~> 1.9"}

なお Config モジュールと mix release コマンドを利用するので Elixir は 1.9 以上が必要です。

プロジェクトを用意する

プロジェクトを作成します。

$ mix phx.new hoge
$ cd hoge

Heroku はリポジトリの設定を .git/config に記録するので、Git のリポジトリを作成しておいてください。 設定が記録できればよいのでコードの変更を commit しておく必要はないのですが、一般的に作業の巻き戻しなどに備えて適宜 commit しながら進めてください。

$ git init
$ git add .
$ git commit -m 'initial commit'

Config を変更する

config ファイルを書き換えます。

書き換えについては Phoenix のドキュメント「Deploying with Releases」のセクション「Runtime configuration」に解説があります。

ファイル名の変更

ディレクトconfig/ にある prod.secret.exs のファイル名を releases.exs に変更します。

releases.exs の編集

releases.exs の内容を編集します。

まず、モジュール Config を利用するように変更します。

use Mix.Configimport Config に書き換えます。

--- a/config/prod.secret.exs
+++ b/config/releases.exs
@@ -2,7 +2,7 @@
 # from environment variables. You can also hardcode secrets,
 # although such is generally not recommended and you have to
 # remember to add this file to your .gitignore.
-use Mix.Config
+import Config

次に Endpoint の設定に server: true を追加します。

--- a/config/prod.secret.exs
+++ b/config/releases.exs
@@ -25,7 +25,8 @@ secret_key_base =
 
 config :hoge, HogeWeb.Endpoint,
   http: [:inet6, port: String.to_integer(System.get_env("PORT") || "4000")],
-  secret_key_base: secret_key_base
+  secret_key_base: secret_key_base,
+  server: true

これは Mix を利用せずに単独でサーバとして起動するための設定です。

  • :server - when true, starts the web server when the endpoint supervision tree starts. Defaults to false. The mix phx.server task automatically sets this to true

Runtime configuration / Phoenix.Endpoint

なお Heroku の制限として、HTTP のポートは Heroku が設定する環境変数 PORT の値を利用する必要があります。

  • The web process must listen for HTTP traffic on $PORT, which is set by Heroku.

Dockerfile commands and runtime / Container Registry & Runtime (Docker Deploys) | Heroku Dev Center

ただこれは自動生成される config に port: String.to_integer(System.get_env("PORT") || "4000") と最初から設定されていますので変更せずこのままで大丈夫です。

また config/releases.exs については、一つ前の記事に簡単にまとめましたので参考にしてみてください。

不要な設定の削除

prod.secret.exs が不要になったので prod.exs 内の prod.secret.exs を読み込んでいる行を削除します。

--- a/config/prod.exs
+++ b/config/prod.exs
@@ -52,4 +52,3 @@ config :logger, level: :info
 
 # Finally import the config/prod.secret.exs which loads secrets
 # and configuration from environment variables.
-import_config "prod.secret.exs"

Dockerfile を用意する

Dockerfile を用意します。 アプリケーション名が現れるのはリリース版のファイルをコピーする部分とサーバを起動する部分のみです。 この二つを書き換えるだけで他のプロジェクトでも基本的に同じ内容で対応できます。

########################################
# ビルド
########################################

FROM elixir:1.9-alpine as build

WORKDIR /app

# ビルドに必要なツールをインストールする
RUN apk add --update git build-base nodejs yarn npm

# Hex と rebar をインストールする
RUN mix local.hex --force && mix local.rebar

# ビルド時の環境変数を設定する
ENV MIX_ENV=prod

# 依存するパッケージをインストールする
COPY mix.exs ./
COPY mix.lock ./
COPY config ./config
RUN mix deps.get --only prod
RUN mix deps.compile

# assets をインストールする
COPY assets ./assets
RUN npm install --prefix ./assets && npm run deploy --prefix ./assets
RUN mix phx.digest

# ビルドする
COPY priv ./priv
COPY lib ./lib
RUN mix compile

# リリース版を構築する
#   リリースの設定を rel/ に用意しているばあいは、それのコピーもしておいてください
# COPY rel ./rel
RUN mix release

########################################
# リリースするイメージを構築する
########################################

FROM alpine:3.10 as web

WORKDIR /app

# 実行時に必要なツールをインストールする
RUN apk add --update bash openssl

# ビルドしたリリース版のファイルをコピーする
#   アプリケーション名の部分 ( `hoge` ) は作成したアプリケーションの名前に合わせてください
COPY --from=build /app/_build/prod/rel/hoge ./

# ユーザを設定する
RUN chown -R nobody: /app
USER nobody

# 実行時の環境変数を設定する
ENV HOME=/app

# サーバを起動する
#   アプリケーション名の部分 ( `hoge` ) は作成したアプリケーションの名前に合わせてください
CMD bin/hoge start

Heroku にデプロイする

Heroku アプリケーションの作成

まず Heroku のコンテナリポジトリにログインします。

$ heroku container:login

次に Heroku に新しいアプリケーションを作成します。 heroku create コマンドを使って、あるいは Heroku のコンソールを利用して作成します。

$ heroku create hoge-with-docker

環境変数の設定

環境変数を設定します。

SECRET_KEY_BASE を設定します。 ここでは mix phx.gen.secret コマンドで生成した値を設定しています。 heroku config:set コマンドを使って、あるいは Heroku のコンソールを利用して設定します。

$ heroku config:set SECRET_KEY_BASE=`mix phx.gen.secret`

データベースの設定

データベースを利用するばあい、データベースの設定をします。 Heroku のアドオンを利用するばあい、heroku addons:create コマンドを使って、あるいは Hroku コンソールを利用して設定します。

$ heroku addons:create heroku-postgresql

アドオンを利用したばあいは接続先の URL が環境変数DATABASE_URL に設定されます。 config/releases.exs の初期状態では DATABASE_URL から接続先の情報を取得するようになっているので、この状態でデプロイすればデータベースに接続できるようになります。

Heroku のアドオン以外のデータベースを利用するばあいは、そのデータベースのURLを DATABASE_URL に設定してください。

$ heroku config:set DATABASE_URL=postgres://USER:PASSWORD@DOMAIN:PORT/DATABASE

Push the image and release

Docker イメージをビルドして Heroku に push します。

$ heroku container:push web

push したイメージをリリースします。

$ heroku container:release web

すべての準備が整ったので、デプロイしたアプリケーションを開きます。 ブラウザでアプリケーションの URL を入力して開くか、あるいは heroku open コマンドでページを開きます。

$ heroku open

データベースのマイグレーション

データベースを利用するばあい、データベースのマイグレーションを実行する必要があります。 通常は mix ecto.migrate コマンドを利用しますがリリース版は Mix を含まないためこのコマンドを実行できません。

このようなばあい、自分でマイグレーションの処理を用意し実行する必要があります。

これについても Phoenix のドキュメントに記載されています。

lib/hoge/マイグレーションを実行する関数を記述した次のような内容のファイル release.ex を追加します。

ファイル名、ファイルの格納ディレクトリは、マイグレーションを実行できれば任意でかまわないのですが、ここではドキュメントに合わせた構成にしています。

# lib/hoge/release.ex

defmodule Hoge.Release do
  @app :hoge

  def migrate do
    for repo <- repos() do
      {:ok, _, _} = Ecto.Migrator.with_repo(repo, &Ecto.Migrator.run(&1, :up, all: true))
    end
  end

  def rollback(repo, version) do
    {:ok, _, _} = Ecto.Migrator.with_repo(repo, &Ecto.Migrator.run(&1, :down, to: version))
  end

  defp repos do
    Application.load(@app)
    Application.fetch_env!(@app, :ecto_repos)
  end
end

これをアプリケーションの eval コマンドで実行します。

Phoenix のドキュメントでは次のような実行例が記載されています。

$ _build/prod/rel/my_app/bin/my_app eval "MyApp.Release.migrate"

今回は Heroku にデプロイしているので Heroku 上でプロセスを実行するので heroku run コマンドを利用します。

またリリースは _build/prod/rel/hoge/ 以下の内容をデプロイしているので実行パスも bin/ 以降を指定すればよく bin/hoge eval という形になります。

全体として。次のようにマイグレーションを実行します。 アプリケーション名の部分 ( hoge ) 、モジュール名の部分 ( Hoge ) は作成されるアプリケーション、モジュールに置き換えて実行してください。

$ heroku run 'bin/hoge eval "Hoge.Release.migrate()"'

WebSocket を利用する

Phoenix.Channel や Phoenix.LiveView などで WebSocket を利用するばあい、 :check_origin を設定する必要があります。

  • :check_origin - configure transports to check origin header or not. May be false, true, a list of hosts that are allowed, or a function provided as MFA tuple. Hosts also support wildcards.

Runtime configuration/ Phoenix.Endpoint

config/releases.exs に :check_origin を追加します。 ここでは環境変数を利用した設定にしています。

# config/releases.exs

config :hoge, HogeWeb.Endpoint,
  http: [:inet6, port: String.to_integer(System.get_env("PORT") || "4000")],
  secret_key_base: secret_key_base,
  check_origin: ["//#{System.get_env("HOST")}"],
  server: true

アプリケーションの環境変数に値を追加します。

$ heroku config:set HOST=hoge-with-docker.herokuapp.com

これで WebSocket のリクエストを受け付けることができるようになりました。

いつか読むはずっと読まない:古典

自分にとって長らくプログラミングスタイルの拠り所になっていたのは間違いなく「プログラム書法」でした。 さすがに現在ではそぐわない内容も多くなりましたが、プログラミングに対する姿勢はこの本で学びました。

「達人プログラマー」(翻訳旧版)を読んだとき、「現代の『プログラム書法』だ」と思ったものでした。

その「達人プログラマー」も現在ではすっかり古典となったようです。 古典であるからこそ、立ち返ってその考えをふたび吸収したいと思います。

プログラム書法 第2版

プログラム書法 第2版

新装版 達人プログラマー 職人から名匠への道

新装版 達人プログラマー 職人から名匠への道

Elixirのreleases.exsの使いどころ

リリースするアプリケーションでは、実行環境に依存する情報をコード内に抱え込まないように、環境変数から設定を取得することが多いと思います。 Elixir では設定情報を config/config.exs に書くことが多いのですが、このファイルはビルド時に読み込まれるため、この中で環境変数の値を取り込んでも実行時に反映されません。

Elixir 1.9 では config の扱いが変わりました。

1.8 までは Mix.Config という Mix のモジュールを利用していましたが、1.9 からは Elixir が直接持つ Config というモジュールを利用するように変更されています。

また、実行環境に合わせた設定をアプリケーションが起動するタイミングでおこないたい、という動機で config/releases.exs が導入されたようです。

アプリケーションをリリースする段になって混乱しないように Elixr 1.9 の config の使い方を確認してみました。

config/config.exs

まず従来からある config/config.exs の挙動を確認してみます。

挙動を確認するためのプロジェクトを用意する

適当なプロジェクトを用意します。

$ mix new hoge
$ cd hoge

1.9 からは config の扱いが変更になったのにともない、 mix new コマンドはディレクトconfig および config ファイルを作成しなくなりました。

config が必要なばあいは自分でディレクトconfig を作成します。

$ mkdir config

config.exs を記述する

config/config.exs ファイルを作成して設定を記述します。

import Config

config :hoge,
  foo: System.get_env("FOO"),
  bar: System.get_env("BAR")

挙動を確認するための関数を用意する

lib/hoge.ex にアプリケーションの設定を表示する関数を追加します。

defmodule Hoge
  def show_env do
    IO.write("foo: ")
    IO.inspect(Application.fetch_env(:hoge, :foo))

    IO.write("bar: ")
    IO.inspect(Application.fetch_env(:hoge, :bar))
  end
end

またリリース版を作成するために lib/hoge/application.ex を用意します。

defmodule Hoge.Application do
  use Application

  def start(_, _) do
    # 環境変数を表示する関数を呼び出す
    Hoge.show_env()

    # 今回は実行を継続する必要がないので環境変数を表示したら終了する
    System.halt()
  end
end

Hoge.Application を callback module として設定します。

(最初の投稿時にこの記述が抜けていました。失礼しました)

defmodule Hoge.MixProject do

  # ...

  def application do
    [
      extra_applications: [:logger],
      mod: {Hoge.Application, []}
    ]
  end

  # ...

end

挙動を確認する

リリース版をビルドします。

$ mix release

実行します。

$ _build/dev/rel/hoge/bin/hoge start
foo: {:ok, nil}
bar: {:ok, nil}

環境変数を設定して実行します。

$ FOO=foo BAR=bar _build/dev/rel/hoge/bin/hoge start
foo: {:ok, nil}
bar: {:ok, nil}

実行時に環境変数を指定しても反映されません。

リリース版をビルドするときに環境変数を設定してみます。

$ FOO=foo BAR=bar mix release

実行します。

$ _build/dev/rel/hoge/bin/hoge start
foo: {:ok, "foo"}
bar: {:ok, "bar"}

環境変数を設定して実行します。

hoge $ FOO=hoge BAR=fuga _build/dev/rel/hoge/bin/hoge start
foo: {:ok, "foo"}
bar: {:ok, "bar"}

実行時の環境変数は影響を与えず、ビルド時に設定した値が表示されることがわかります。

config/releases.exs

次に config/releases.exs を作成して設定を記述します。

releases.exs を記述する

import Config

config :hoge,
  bar: System.get_env("BAR")

挙動を確認する

リリース版をビルドします。

$ mix release

実行します。

$ _build/dev/rel/hoge/bin/hoge start
foo: {:ok, nil}
bar: {:ok, nil}

環境変数を設定して実行します。

$ FOO=hoge BAR=fuga _build/dev/rel/hoge/bin/hoge start
foo: {:ok, nil}
bar: {:ok, "fuga"}

config/releases.exs環境変数を利用するようにした bar は実行時の環境変数の値が反映されることがわかります。

次にビルド時に環境変数を設定します。

$ FOO=foo BAR=bar mix release

実行します。

$ _build/dev/rel/hoge/bin/hoge start
foo: {:ok, "foo"}
bar: {:ok, nil}

ビルド時に環境変数 BAR にも値を設定しましたが、実行時に設定していないため bar の値は nil になっています。 またここから、 config.exsreleases.exs に同じ設定を記述したばあい、releases.exs の設定が優先されることがわかります。

環境変数を指定して実行します。

$ FOO=hoge BAR=fuga _build/dev/rel/hoge/bin/hoge start
foo: {:ok, "foo"}
bar: {:ok, "fuga"}

config/release.exs で設定していない foo はビルド時の環境変数の値になっています。 一方 config/releases.exs で設定した bar は慈光寺の環境変数の値になっています。

releases.exs の在り処

最後に。 releases.exs がどこで利用されているか確認します。

$ find . -name releases.exs
./config/releases.exs
./_build/dev/rel/hoge/releases/0.1.0/releases.exs

config/releases.exs はリリース版に同梱されていることがわかります。

またアプリケーションを起動するスクリプト _build/dev/rel/hoge/bin/hoge を読んでみると、_build/dev/rel/hoge/releases/0.1.0/sys.config のコピーを読み込んでいることがわかります。

このファイルの内容を確認すると次のようになっています。 実際のファイルではコメント行以外は一行で記述されていますが、ここでは読みやすいように改行とインデント、およびバイナリ部分にコメントを追加しました。

Erlang の内容に踏み込んでしまうので深追いはしませんが、同梱された releases.exsConfig.Reader で利用するように設定されていることがわかります。

%% coding: utf-8
%% RUNTIME_CONFIG=true
[
  {
    hoge,
    [
      {foo, nil},
      {bar, nil}
    ]
  },
  {
    elixir,
    [
      {
        config_providers,
        #{
          '__struct__' => 'Elixir.Config.Provider',
          config_path => {
            system,
            % "RELEASE_SYS_CONFIG"
            <<82,69,76,69,65,83,69,95,83,89,83,95,67,79,78,70,73,71>>,
            % ".config"
            <<46,99,111,110,102,105,103>>
          },
          extra_config => [
            {
              kernel,
              [
                {start_distribution, true}
              ]
            }
          ],
          providers => [
            {
              'Elixir.Config.Reader',
              {
                system,
                % "RELEASE_ROOT"
                <<82,69,76,69,65,83,69,95,82,79,79,84>>,
                % "/releases/0.1.0/releases.exs"
                <<47,114,101,108,101,97,115,101,115,47,48,46,49,46,48,47,114,101,108,101,97,115,101,115,46,101,120,115>>
              }
            }
          ],
          prune_after_boot => false
        }
      }
    ]
  },
  {
    kernel,
    [
      {start_distribution, false}
    ]
  }
].

いつか読むはずっと読まない:mismatch

昨年まで 3 年近く関わったプロジェクトではバックエンドの部分を担ったため、エンドユーザはあまり意識せずに開発をしていました。

今年から再びフロントエンドを含むウェブサービスの開発に参加することになりましたが、一番に戸惑ったのがフロントエンドの書き方、特にテストの書き方を結構忘れてしまっていたこと。 幸いすぐに勘を取り戻すことができましたが、そういったものに気を取られることがなくなるとアプリケーションが提供している操作そのものに意識が向くようになります。

ミスマッチ 見えないユーザーを排除しない「インクルーシブ」なデザインへ

ミスマッチ 見えないユーザーを排除しない「インクルーシブ」なデザインへ

  • 作者: キャット・ホームズ,ジョン・マエダ,大野千鶴
  • 出版社/メーカー: ビー・エヌ・エヌ新社
  • 発売日: 2019/03/15
  • メディア: 単行本
  • この商品を含むブログを見る

Phoenix.LiveView 事始め(subscribeとbroadcast)

前回の続きです。

前回、「バージョン 0.1 が公開され…」と書いたばかりなのに、今回の記事を書くまでの十日足らずの間にバージョン 0.2 が公開されてしまいました。

それはそれとして。

今回は Phoenix.LiveView の app で subscribe と broadcast を使って、複数のユーザ(ブラウザ)で通信させようという試みです。

使うサンプルはクリックしたセルの色が同期して変化する Phoenix app です。

モジュールを追加する手前まで進む

LiveView を利用できるように設定するところまでは同じですので前回の記事を参照しながら、「準備」「パッケージを追加する」「Endpoint を編集する」「ソケットのクライアントを設定する」「salt を設定する」まで進みます。

ここでは live_click という app 名で作成しています。

$ mix phx.new live_click --no-ecto

まずは単独の app を作成する

live モジュール

ディレクトlib/live_click_web/live を作成し、そこに click_live.ex を作成してモジュール LiveClickWeb.ClickLive を定義します。

defmodule LiveClickWeb.ClickLive do
  use Phoenix.LiveView

  def mount(_session, socket) do
    new_socket =
      socket
      |> assign(:effects, %{})
    {:ok, new_socket}
  end

  def render(assigns) do
    Phoenix.View.render(LiveClickWeb.ClickView, "index.html", assigns)
  end

  def handle_event("cell", %{"row" => row, "col" => col}, socket) do
    new_socket =
      socket
      |> assign_cell_color(String.to_integer(row), String.to_integer(col))
    {:noreply, new_socket}
  end

  def assign_cell_color(socket, row, col) do
    effects = socket.assigns.effects

    new_effect =
      case Map.get(effects, {row, col}) do
        :red -> :blue
        :blue -> :green
        :green -> :white
        _ -> :red
      end

    socket
    |> assign(:effects, Map.put(effects, {row, col}, new_effect))
  end
end

view モジュール

lib/live_click_web/views/click_view.ex を作成してモジュール LiveClickWeb.ClickView を定義します。

defmodule LiveClickWeb.ClickView do
  use LiveClickWeb, :view
end

テンプレートとスタイル

lib/live_click_web/templates/click/index.html.leex を作成してテンプレートを定義します。

<div>
  <%= Enum.map (0..9), fn row -> %>
    <div>
      <%= Enum.map (0..9), fn col -> %>
        <div class="cell <%= Map.get(@effects, {row, col}) %>" phx-click="cell" phx-value-row="<%= row %>" phx-value-col="<%= col %>">
          <%= row %><%= col %>
        </div>
      <% end %>
    </div>
  <% end %>
</div>

また assets/css/app.css を編集してスタイルを追加します。

@import "./phoenix.css";

/* ここから下を追加 */

.cell {
  display: inline-block;
  height: 50px;
  width: 50px;
  border: solid thin #ccc;
  text-align: center;
  line-height: 50px;
  margin-bottom: 5px;
}

.red {
  background-color: red;
}

.green {
  background-color: green;
}

.blue {
  background-color: blue;
}

.white {
  background-color: white;
}

ルーティングを変更する

lib/live_click_web/router.ex を編集します。

   scope "/", LiveClickWeb do
     pipe_through :browser
 
-    get "/", PageController, :index
+    live "/", ClickLive
   end

動作を確認する

iex コマンドあるいは mix コマンドで Phoenix app をローカルに起動し、http://localhost:4000 にアクセスして動作を確認します。

$ iex -S mix phx.server

セルをクリックすると、クリックしたセルの色がクリックのたびに 白 → 赤 → 青 → 緑 → 白 と変化すれば成功です。

subscribe と broadcast と handler を追加する。

Phoenix.LiveView 自体が WebSocket を利用しているため、ここから少しコードを追加するだけで他のブラウザにイベントを送ることができるようになります。

subscribe

イベントを subscribe するために LiveClickWeb.ClickLive.mount/2LiveClickWeb.Endpoint.subscribe(@topic) の一行を追加します。 これだけで broadcast されたイベントを受け取ることができるようになります。

  @topic "live_click:cells"

  def mount(_session, socket) do
    LiveClickWeb.Endpoint.subscribe(@topic)
    new_socket =
      socket
      |> assign(:effects, %{})
    {:ok, new_socket}
  end

関数の詳細はドキュメントを参照してください。

broadcast

イベントを broadcast するために LiveClickWeb.Endpoint.broadcast_from/4 の一行を追加します。 今回は LiveClickWeb.ClickLive. assign_cell_color/3 でローカルで発生したイベントを処理をしているのでここに追加します。

関数の第二引数には subscribe したトピックを文字列で、第三引数にはイベントを文字列で、第四引数には送信したいパラメータをマップで設定します。

  def assign_cell_color(socket, row, col) do
    effects = socket.assigns.effects

    new_effect =
      case Map.get(effects, {row, col}) do
        :red -> :blue
        :blue -> :green
        :green -> :white
        _ -> :red
      end

    LiveClickWeb.Endpoint.broadcast_from(self(), @topic, "click", %{key: {row, col}, value: new_effect})

    socket
    |> assign(:effects, Map.put(effects, {row, col}, new_effect))
  end

broadcast 元以外にイベントを送るために broadcast_from/4 を利用しましたが、全体に送るには broadcast/3 を利用します。

関数の詳細はドキュメントを参照してください。

handler

broadcast されたイベントはモジュール LiveClickWeb.ClickLive へのメッセージとして届きます。メッセージをハンドリングするため LiveClickWeb.ClickLive.handle_info/2 を記述します。

第一引数は broadcast の引数の内容を格納したマップになります。 :topic にトピックが、:event にイベントが、:payload にその他のパラメータが格納されます。

  def handle_info(%{topic: @topic, event: "click", payload: %{key: key, value: value}}, socket) do
    effects = socket.assigns.effects
    new_socket =
      socket
      |> assign(:effects, Map.put(effects, key, value))

    {:noreply, new_socket}
  end

関数の詳細はドキュメントを参照してください。

実行

app を起動し、ブラウザのウィンドウを二つ以上開きます。 一つのブラウザでクリックした内容が他のブラウザにも反映されることが確認できます。

一つ注意点。 このサンプルではセルの状態を永続化しているわけではないので、表示の内容のすべてが同期されるわけではありません。 あるセルをクリックしたことによるそのセルの状態の変化のみが伝わるようになっています。

いつか読むはずっと読まない:THE LONG WAY TO A ...

銀河共同体の中で、様々な星系出身の容姿も文化も価値観も違うクルーが一つの船で目的地に向かう。古典的なスペオペがわくわく感を誘います。

とはいえ。「古典的」とはあえて書いてみました。設定だけを切り出すと懐かしいスペオペの雰囲気があるのですが、書かれた時代背景が作品に現れるのはこの作品にも違いはなく、やはり現代の作品なのだな、と感じます。

銀河核へ 上 (創元SF文庫)

銀河核へ 上 (創元SF文庫)

銀河核へ 下 (創元SF文庫)

銀河核へ 下 (創元SF文庫)

Phoenix.LiveView 事始め

先月末にバージョン 0.1 が公開され、Hex からインストールできるようになりました。

これを機に Phoenix.LiveView に挑戦です。

この記事では、app 作成から LiveView で表示を動かすまでの作業を、ただ淡々と書いてゆきます。

準備

適当な Phoenix app を用意します。

以降の説明のために、ここでは DB (Ecto) を利用しない app を新規に作成します。

$ mix phx.new my_app --no-ecto
$ cd my_app

パッケージを追加する

mix.exs を編集して phoenix_live_view を追加します。

--- a/mix.exs
+++ b/mix.exs
@@ -38,7 +38,8 @@ defmodule MyApp.MixProject do
       {:phoenix_live_reload, "~> 1.2", only: :dev},
       {:gettext, "~> 0.11"},
       {:jason, "~> 1.0"},
-      {:plug_cowboy, "~> 2.0"}
+      {:plug_cowboy, "~> 2.0"},
+      {:phoenix_live_view, "~> 0.1"}
     ]
   end
 end
$ mix deps.get

assets/package.jsonJavaScript で利用するパッケージの依存情報を追加します。

--- a/assets/package.json
+++ b/assets/package.json
@@ -7,7 +7,8 @@
   },
   "dependencies": {
     "phoenix": "file:../deps/phoenix",
-    "phoenix_html": "file:../deps/phoenix_html"
+    "phoenix_html": "file:../deps/phoenix_html",
+    "phoenix_live_view": "file:../deps/phoenix_live_view"
   },
$ npm install --prefix assets

Endpoint を編集する

lib/my_app_web/endpoint.ex を編集し、 LiveView で使うソケットを設定します。

--- a/lib/my_app_web/endpoint.ex
+++ b/lib/my_app_web/endpoint.ex
@@ -5,6 +5,8 @@ defmodule MyAppWeb.Endpoint do
     websocket: true,
     longpoll: false
 
+  socket "/live", Phoenix.LiveView.Socket

ソケットのクライアントを設定する

assets/js/app.js を編集し、ソケットに接続するためのクライアントのコードを追加します。

--- a/assets/js/app.js
+++ b/assets/js/app.js
@@ -15,3 +15,8 @@ import "phoenix_html"
 //
 // Local files can be imported directly using relative paths, for example:
 // import socket from "./socket"
+
+import LiveSocket from "phoenix_live_view"
+
+let liveSocket = new LiveSocket("/live")
+liveSocket.connect()

salt を設定する

config/config.exs の endpoint の設定の項目に :live_view を追加し、キーワードリストに :signing_salt を設定します。

--- a/config/config.exs
+++ b/config/config.exs
@@ -10,11 +10,12 @@ use Mix.Config
 # Configures the endpoint
 config :my_app, MyAppWeb.Endpoint,
   url: [host: "localhost"],
   secret_key_base: "QshB2lH5dWIXtZFX9mewWHeY/Lt/EpyQv/ErFXjXMfDmstWH3eQ9dVqM2rfdGLBX",
   render_errors: [view: MyAppWeb.ErrorView, accepts: ~w(html json)],
-  pubsub: [name: MyApp.PubSub, adapter: Phoenix.PubSub.PG2]
+  pubsub: [name: MyApp.PubSub, adapter: Phoenix.PubSub.PG2],
+  live_view: [signing_salt: "some-secure-salt"]

モジュールを追加する

ディレクトlib/my_app_web/live を作成し LiveView のモジュール MyAppWeb.SampleLIveを定義したファイル lib/my_app_web/live/sample_live.ex を作成します。

defmodule MyAppWeb.SampleLive do
  use Phoenix.LiveView

  def render(assigns) do
    ~L"""
    Hello Phoenix.LiveView world!
    """
  end

  def mount(_session, socket) do
    {:ok, socket}
  end
end

router を設定する

lib/my_app_web/router.ex を編集し、MyAppWeb.SampleLIve を利用する routing を追加します。

--- a/lib/my_app_web/router.ex
+++ b/lib/my_app_web/router.ex
@@ -1,26 +1,28 @@
 defmodule MyAppWeb.Router do
   use MyAppWeb, :router
+  import Phoenix.LiveView.Router
 
   pipeline :browser do
     plug :accepts, ["html"]
     plug :fetch_session
     plug :fetch_flash
     plug :protect_from_forgery
     plug :put_secure_browser_headers
   end
 
   pipeline :api do
     plug :accepts, ["json"]
   end
 
   scope "/", MyAppWeb do
     pipe_through :browser
 
     get "/", PageController, :index
+    live "/sample", SampleLive
   end

最初の表示

app を起動し、http://localhost:4000/sample にアクセスします。

$ iex -S mix phx.server

MyAppWeb.SampleLIverender/1 に記述した内容がレンダリングされ表示されました。

view と template を追加する

LiveView のモジュール内に sigil ( ~L ) で記述する代わりに view と template で表示するように変更します。

新規に view のファイル lib/my_app_web/views/sample_view.ex を作成してモジュール MyAppWeb.SampleView を定義します。

defmodule MyAppWeb.SampleView do
  use MyAppWeb, :view
end

同じく新規に template のファイル lib/my_app_web/templates/sample/show.html.leex を作成してテンプレートを記述します。LiveView のテンプレートは拡張子が .leex になります。

<h1><%= @message %></h1>

モジュール MyAppWeb.SampleLiverender/1 の記述を上で追加した view と template を使うように変更します。

  def render(assigns) do
    Phoenix.View.render(MyAppWeb.SampleView, "show.html", message: "Hello Phoenix.LiveView world!")
  end

:message で与えた文字列が、テンプレートに記述したタグ <h1> で装飾されて表示されることが確認できます。

click をハンドリングする

lib/my_app_web/templates/sample/show.html.leex を次のように変更します。

<h1><%= @message %></h1>
<button phx-click="add" phx-value-char="A">A</button>
<button phx-click="add" phx-value-char="B">B</button>
<button phx-click="add" phx-value-char="C">C</button>
<button phx-click="clear">clear</button>
<div>
  > <%= @str %>
</div>

変更すると右のようにボタンが表示されます。

タグ button に指定した phx-click が click のイベントとして LiveView のモジュールで定義するハンドラ handle_event/3 に渡されます。 また phx-value-* で指定した値がイベントの値として一緒にハンドラに渡されます。

MyAppWeb.SampleLivehandle_event/3 を実際に追加します。

defmodule MyAppWeb.SampleLive do
  use Phoenix.LiveView

  def render(assigns) do
    Phoenix.View.render(MyAppWeb.SampleView, "show.html", message: "Hello Phoenix.LiveView world!", str: assigns.str)
  end

  def mount(_session, socket) do
    {:ok, assign(socket, :str, "")}
  end

  def handle_event("add", %{"char" => char}, socket) do
    str = socket.assigns.str
    new_socket =
      socket
      |> assign(:str, str <> char)
    {:noreply, new_socket}
  end

  def handle_event("clear", _, socket) do
    {:noreply, assign(socket, :str, "")}
  end
end

A, B, C の各ボタンで文字列に文字が追加され、clear ボタンで文字列がクリアされます。

フォームのイベントをハンドリングする

lib/my_app_web/templates/sample/show.html.leex にフォームを追加します。また入力結果を表示するための要素も追加します。 フォームで変更が発生すると phx-change で指定されたイベントが発生します。また submit した場合は phx-submit で指定したイベントが発生します。

<h1><%= @message %></h1>
<button phx-click="add" phx-value-char="A">A</button>
<button phx-click="add" phx-value-char="B">B</button>
<button phx-click="add" phx-value-char="C">C</button>
<button phx-click="clear">clear</button>
<div>
  > <%= @str %>
</div>

<hr />

<form phx-change="update" phx-submit="submit">
  <input type="text" name="text">
</form>
<div>
  > <%= @text %>
</div>
<ul>
  <%= Enum.map(@texts, fn text -> %>
    <li><%= text %></li>
  <% end) %>
</ul>

LiveView のモジュールにハンドラを追加します。

イベント update が発生すると input タグの name で指定した値をパラメータとしてハンドラが呼び出されます。

ここでは input タグに文字列の入力があると、それを反転した文字列を表示し、submit されるとその反転された文字列をリストに追加する処理を追加しました。

defmodule MyAppWeb.SampleLive do
  use Phoenix.LiveView

  def render(assigns) do
    params = [
      message: "Hello Phoenix.LiveView world!",
      str: assigns.str,
      text: assigns.text,
      texts: assigns.texts
    ]
    Phoenix.View.render(MyAppWeb.SampleView, "show.html", params)
  end

  def mount(_session, socket) do
    new_socket =
      socket
      |> assign(:str, "")
      |> assign(:text, "")
      |> assign(:texts, [])
    {:ok, new_socket}
  end

  def handle_event("add", %{"char" => char}, socket) do
    str = socket.assigns.str
    new_socket =
      socket
      |> assign(:str, str <> char)
    {:noreply, new_socket}
  end

  def handle_event("clear", _, socket) do
    {:noreply, assign(socket, :str, "")}
  end

  def handle_event("update", %{"text" => text}, socket) do
    new_socket =
      socket
      |> assign(:text, String.reverse(text))
    {:noreply, new_socket}
  end

  def handle_event("submit", _, socket) do
    new_socket =
      socket
      |> assign(:text, "")
      |> assign(:texts, [socket.assigns.text | socket.assigns.texts])
    {:noreply, new_socket}
  end
end

実行結果です。

ここでは form タグを直接記述したので phx-change, phx-submit という形で記述しましたが、Phoenix.HTML.Form.form_for/3 を利用する場合はドキュメントにあるように、オプションに :phx_change, :phx_submit とハイフンをアンダスコアに置き換えたキーで指定します。

いつか読むはずっと読まない:博物館の後ろ側、あるいは本当の顔

研究者から見た大英自然史博物館の様子を語った一冊。

博物館には一般の来場者の目の届かないところに膨大な資料が保存され様々な人々の営みがあることに目を向けさせられます。

乾燥標本収蔵1号室―大英自然史博物館 迷宮への招待

乾燥標本収蔵1号室―大英自然史博物館 迷宮への招待

へんなものみっけ! (4) (ビッグコミックス)

へんなものみっけ! (4) (ビッグコミックス)