このブログでも何度か Node.js のネタを扱ってますが、非同期処理に悩まされることが多いので、自分の理解の意味でもまとめておくことにしました。

まず理解の大前提として、Node.js はシングルスレッドで動作するため、いわゆる並列処理はできない仕様になっています。そして非同期に処理を実行することができます。これによって並列処理ができなくても、何かの時間のかかる処理があった場合にその終了を待たずに次の処理に進むことができることを意味しています。　ただ、この辺りがややこしく難解になっていることも事実です。

例えば REST API などの HTTP リクエストを行って、その結果が得られたら、その得られた結果の JSON オブジェクトの値を使って処理をする、などというよくあるケースでもこの問題に直面します。

まずは何が難解なのかを紹介します。REST API だとローカル環境で気軽に試せないので、わざと実行に時間のかかる関数を用意して説明します。

例えばこのような処理を考えてみます：

// test.js

// わざと１秒かけてから、パラメータの２倍の数値を出力する関数
function func1( x ){
  setTimeout( function(){
    console.log( 2 * x );
  }, 1000 );
}

// 初期値を設定して出力
var n0 = 10;
console.log( 'n0 = ' + n0 );

// 初期値を上記関数のパラメータに入れて実行
func1( n0 );

この中では func1 という関数を定義しています。setTimeout を使ってわざと１秒（1000ミリ秒）待ってから、パラメータの値の２倍を画面に出力する、という関数です。　この関数を n0 （=10 に設定）という変数をパラメータにして実行する、というものです。なので "20" という結果が出力されることを期待しています。

この内容を test.js というファイルに保存して、実行してみます（青字部分が出力結果）：

$ node test
n0 = 10
20

期待通りに "20" と出力されました。とりあえずここまでは成功です。


さて問題はここからです。上記例では関数 func1 の中で console.log が実行されて出力までを行いました。これを func1 からは与えた数値を２倍した結果を受け取るようにして、func1 の外側で出力するように変更してみます。深く考えずにやるとこんな感じでしょか？

// test.js（注　正しく動きません）

// わざと１秒かけてから、パラメータの２倍の数値を出力する関数
function func1( x ){
  setTimeout( function(){
    console.log( 2 * x );
  }, 1000 );
}

// わざと１秒かけてから、パラメータの２倍の数値を戻す関数
function func2( x ){
  setTimeout( function(){
    return ( 2 * x );
  }, 1000 );
}

// 初期値を設定して出力
var n0 = 10;
console.log( 'n0 = ' + n0 );

// 初期値を上記関数のパラメータに入れて実行し、戻り値を出力
var n1 = func2( n0 );
console.log( 'n1 = ' + n1 );

func1 をほぼコピペして func2 という関数を作りました。console.log の代わりに return にして、値を返すようにしています。呼び出し元からはこの func2 を実行して、得られた結果を出力するようにしています。

これを先程と同様に実行するとこうなります：

$ node test
n0 = 10
n1 = undefined

n0（10）の値の２倍の "20" という結果を期待していたのですが、"undefined" と表示されてしまいます（正確に書くと、上記の２行はすぐに表示されますが、更に１秒くらい経過してから終了します）。この理由は最初に書いたように func2 は非同期に実行されているので、return の行が実行されるまでには１秒かかります。しかしその前に（return の行が実行される前に）関数そのものの処理は終了してしまいます。つまり値が戻る前に（戻っていない値を受け取ることになっている）n1 という変数を出力しているので "undefined" になっているのでした。

このように、期待通りに動かなかった理由は明白なのですが、ではどうすればこの関数が期待通りに動く（１秒後に与えられた結果を戻り値として戻し、受け取った側がその値を出力する）ようにできるでしょうか？これが今日紹介する大きなテーマです。


結論を先に紹介すると、ここで Promise オブジェクトを使って関数を修正し、受け取った側もその変更に合わせて一部書き直す必要があります。具体的には以下のように修正します：

// test.js

// わざと１秒かけてから、パラメータの２倍の数値を出力する関数
function func1( x ){
  setTimeout( function(){
    console.log( 2 * x );
  }, 1000 );
}

// わざと１秒かけてから、パラメータの２倍の数値を戻す関数
function func2( x ){
  return new Promise( function( resolve ){
    setTimeout( function(){
      resolve( 2 * x );
    }, 1000 );
  });
}

// 初期値を設定して出力
var n0 = 10;
console.log( 'n0 = ' + n0 );

// 初期値を上記関数のパラメータに入れて実行し、戻り値を出力
func2( n0 ).then( function( n1 ){
  console.log( 'n1 = ' + n1 );
});

まず関数 func2 側は、Promise オブジェクトを新規に作成します。Promise オブジェクトは処理が成功した場合の関数をパラメータに指定します。上図だと

function( resolve ){
  setTimeout( function(){
    resolve( 2 * x );
  }, 1000 );
}

という関数がパラメータに指定されているので、成功するとこの関数が実行されます（今回は使っていませんが、第二パラメータを指定した場合は失敗時に実行する処理を指定したことになります）。この処理の中で１秒待って、指定したパラメータを２倍して resolve とする、ということになります。

そしてこの関数 func2 を呼び出す側も少し変更が必要になります。 func2() 関数の実行結果をそのまま変数として受け取るのではなく、成功した場合（今回の例だと１秒待って２倍になった値が返された場合）の処理を .then() 内に渡して処理することになります。この then 内の処理で計算結果（resolve で処理された内容）を n1 という変数で受け取って console.log で表示する、という内容にしています。

こうして修正した test.js を実行すると、以下のような結果になります（実際には n0 = 10 がすぐに表示され、１秒くらい待ってから n1 = 20 の行が表示されて終了します）：

$ node test
n0 = 10
n1 = 20

Node.js の関数内で非同期処理を実行して、その非同期処理の終了を待って値を受け取るような関数を作る場合は、Promise オブジェクトを使って上記のように記述します、という紹介でした。非同期実行に慣れていないと、この辺りで戸惑うことが多いと感じたので、まとめておきました。

タグ ：

#nodejs

#promise

#sync

#async

#rest

#api

#json

とある REST API を使っていて気付いたこと／考えさせられたことをまとめてみました。明快な結論や提案があるわけではなく、グダグダに感じられる内容かもしれないので、あらかじめご了承ください。


そのとある REST API を使ったウェブアプリケーションを作って運用している中で、おかしな挙動に気付くことがありました。以前は問題なく動いていたのに、あるタイミングで実行すると期待通りに動かない、という「まあまあよくある」ケースです。自分のケースでは動かないというよりも、タイムアウトを起こすような挙動になっていました。ただ REST API そのものが止まっている様子はない、というケースでした。

自分のソースコードでは一応エラーハンドリングはしていたつもりでしたが、REST API がエラーを起こしている様子もなく、原因究明に時間を要するものでした。結論としては自分のアプリケーションコードを見ていてもよく分からず、REST API のユニットテストのようなツールを動かした結果気付くことがありました。

それがこちら：



・・・わかるでしょうか？ REST API を実行したレスポンス本文が Response Body に、ステータスコードが Response Code に記述されています。これによるとレスポンス本文は

{
  "status": "ERROR",
  "statusInfo": "daily-transaction-limit-exceeded"
}

となっていて、"daily-transaction-limit-exceeded" が原因のエラーが発生している、という内容でした。この API には Daily Transaction Limit（１日で使える回数の上限）が決められていて、その上限に達したのでもう実行できない、という内容です。これに関してはそういう条件で使っている API なので、なるほど、エラーの原因はわかりました。

問題はこの REST API を実行したステータスコードが 200 になっている点です。HTTP ステータスコードの分類とその意味についてはウィキペディアなどを参照していただきたいのですが、簡単にいうとこんな感じで分類されています：

コード	意味	考えられる原因など
2xx（200番台）	成功	-
4xx（400番台）	クライアントエラー	認証が必要、アクセス権がない、URLが間違っている、タイムアウト、、、
5xx（500番台）	サーバーエラー	アプリケーションエラー、不正なゲートウェイが利用されている、、、

200 番台は成功。400 番台と 500 番台がエラーで、それぞれクライアント側のエラーなのか、サーバー側のエラーなのかを分類しています。

で、今回のケースですが、実行結果はエラーなのに 200 番のステータスコードが返されているのでした。自分のプログラムコードの中では「200 が返ってきたら成功」と決めつけて実装していたため、このようなケースに対処できていなかったのでした。


ここまでが実際に目の当たりにしたエラーとその原因でした。以下はこの件に関して自分が考えたことです。


自分を弁護する意味で「えー、でもそれっておかしくない？　エラーなんだからスタータスコードは 400 番台なり 500 番台で返ってくるべきでは？」という考えもないわけではありません。ただ今回のケースではこれも難しいような、つまり 200 番のステータスコードがあながち間違ってはいないような気もしています。

その理由として、まず「これはクライアントエラーなのか？それともサーバーエラーなのか？どちらかに分類できるのか？」という問題です。これに関してはどちらとも言えるし、どちらとも言えないと思っています。

実は 402 番のステータスコードは "Payment Required" 、つまり（お金を払わないといけないんだけど）払ってないエラー、と定義されています。が、実際には定義だけで実装されていない、つまり将来のための定義とされているのでした。また厳密には支払い契約を結んで使っているわけではなく、「この条件で１日○○回使える」というルールの下で利用しているだけなので、402 番に（クライアントエラーに）該当するエラーであるとは考えにくいのです。

※本来の意味とは違いますが、「権限がない」に該当するのではないかと言われると、まあ・・・　という考え方もあるとは思います。ただそれをクライアントエラーとして返してもクライアント側はどうにもできないので、やはり 400 番台エラーには該当しないと思います。

ではサーバーエラーなのか？というと、これも該当しないと思います。プログラミングにミスがあったわけではなく、「実行したら、『実行できない』という結果が返ってきた」のは、正しく実行された（結果が期待通りではなかった）とも言えます。そう考えると、そもそも今回の件は REST API レベルではエラーですらないとも言えます。


そう考えると、今のように API を組み合わせてアプリケーションを作ることが珍しくない環境においては、200 番のステータスコードが返ってきてもエラーの可能性を疑ってコーディングする必要があるのかも、と思うようになりました。このケースであれば実装側が工夫すれば（というか、そもそもちゃんと色んなケースを想定してエラーハンドリングしていれば）防げるものです。

そういう意味でもいい反省の機会でした。　でも今後は同様のケースを想定した「成功でもエラーでもないステータス」が出て来る可能性もありますよね。。

タグ ：

#http

#status

#code

#rest

#api

#error

メール送信（送信だけじゃないけど）サービスの最大手と思われる SendGrid を使う機会がありました。SDK や API を使って、メールを送信できるサービスです。



メール送信そのものは（sendmail などを使えば）単純に実現できますが、一度に大量のメールを送る場合や迷惑メール対策など、本格的に使おうとすると色々な面倒が待っています。そういう面倒な所を一手に引き受けて、心配なくメール送信が実現できる、というサービスです。

この SendGrid によるメール送信ですが、ダッシュボード画面から目的の相手にインタラクティブに送信するだけではなく、プログラミングのためのインターフェースが公開されているので、自分の作るアプリケーションから利用することもできます。ただ実際に送信するサンプルを Java でググると、多くの場合 SDK を使ったものが見つかります。自分は SDK ではなく Web API(REST API) での実現を考えていたので挑戦してみました。ウェブ上にあまり資料がなかったこともあって、その手順を以下に紹介します。


まず最初に大事なこと。SendGrid Web API の最新バージョンは V3 ですが、V2 を使います。SendGrid の推奨でもあります：
https://support.sendgrid.kke.co.jp/hc/ja/articles/206231901-Web API v2とv3どちらを利用すべきでしょうか？-


というわけで、Web API V2 の Mail API を使って実装することにします。リファレンスはこちらです：
https://sendgrid.kke.co.jp/docs/API_Reference/Web_API/mail.html


これを読むと、「メールを送信して結果を JSON で受け取る」場合は以下の様な REST API を実行することになります（これは curl コマンドで実行する場合の例）：

$ curl -X POST https://api.sendgrid.com/api/mail.send.json -H 'Authorization:Bearer SG.*****' -d 'to=user1@recipient.com&subject=abcd&from=info@from.com&html=<b>ハロー</b>、ワールド'

上記コマンドは info@from.com ユーザーから user1@recipient.com ユーザーへ、メールサブジェクトは "abcd" 、本文は HTML で "<b>ハロー</b>、ワールド"（HTML として送信しているので、ハローだけが太字になります）を送信する場合のコマンドになります。 user1@recipient.com は送信先なので実在している必要がありますが、送信アドレスである info@from.com は実在している必要はありません。またヘッダの認証情報として使っている SG. で始まる文字列は SendGrid から取得した api key です。SendGrid のアカウントをお持ちで、まだ api key を取得していない場合、取得方法についてはこちらを参照してください。

上記 curl コマンドは（入力ミスなどがなければ）正しく実行されて、メールも送信されるはずです。つまり正しいコマンドです。これを REST API と見なして、同じ処理を Java で実装しなおせばいいわけですが、これが意外と手間取りました。

まず最初に、普段使っている Jakarta Commons HTTP Client 3.1 （メンテナンスモード）を使って、こんなコードを書いてみました（あらかじめ書いておきますが、以下のコードでは期待通りに動きません）：

  :
public int sendMail( String to, String subject, String html ){
  int r = 0;

  try{
    String data = "to=" + to + "&from=info@from.com&subject=" + subject + "&html=" + html;
    PostMethod method = new PostMethod( "https://api.sendgrid.com/api/mail.send.json" );
    method.setRequestHeader( "Authorization", "Bearer SG.*****" );
    method.setRequestBody( data );
    HttpClient client = new HttpClient();
    int sc = client.executeMethod( method );
    String json = method.getResponseBodyAsString();
      :
    r = 1;
  }catch( Exception e ){
    mothod.setRequest
    e.printStackTrace();
    r = -1;
  }

  return r;
}
  :

オプションで指定している内容は curl コマンドのものと同じです（例えば Content-Type ヘッダを指定していませんが、curl でも指定せずに動いていたので）。ただこの sendMail 関数を to = user1@recipient.com, subject =  abcd, html = <b>ハロー</b>、ワールド というパラメータで実行した場合、ステータスコード（上記コード内の sc 変数）の値は 400 となり、また実行結果である json 変数の値は以下のようなものになりました：

{"errors":["Empty from email address (required)"],"message":"error"}

「必須項目である from 値が空である」というエラーメッセージのように見えます。しかしその値は上記のようにハードコーディングで入力しているつもりでした。

これまでも HTTP Client を Java で実装する場合はこの HTTPClient 3.x を使うことが多かったし、今回のようなポスト時のエラーに遭遇したことはなかったのですが・・・　まずここで躓きました。


次に試したのはポスト方法の変更です。sendMail 関数を以下の様な形に変え、ポストデータをプレーンテキストで送信するのではなく NameValuePair 配列で送信するように変更してみました（これもまだ期待通りには動きません）：

  :
public int sendMail( String to, String subject, String html ){
  int r = 0;

  try{
    PostMethod method = new PostMethod( "https://api.sendgrid.com/api/mail.send.json" );
    method.setRequestHeader( "Authorization", "Bearer SG.*****" );
    List<namevaluepair> params = new ArrayList<namevaluepair>();
    params.add( new NameValuePair( "to", to ) );
    params.add( new NameValuePair( "from", "info@from.com" ) );
    params.add( new NameValuePair( "subject", subject ) );
    params.add( new NameValuePair( "html", html ) );
    method.setRequestBody( ( NameValuePair[] )params.toArray( new NameValuePair[0] ) );
    HttpClient client = new HttpClient();
    int sc = client.executeMethod( method );
    String json = method.getResponseBodyAsString();
      :
    r = 1;
  }catch( Exception e ){
    mothod.setRequest
    e.printStackTrace();
    r = -1;
  }

  return r;
}
  :

自分としては先程のコードと同じことを記載しているつもりでした。が、このコードは一応動いて、ステータスコードは 200 （成功）を返してくれます。

しかし、実際に送られてくるメールを受け取ると、残念ながら日本語部分が全て ? という文字に化けてしまっていました。。

　（↑　ハロー、ワールド　という結果を期待していたが文字化け）


文字化けということは文字コードの指定と実際の文字コードが違っていると読み、であれば強制的に UTF-8 で指定すれば・・・　と考えたのですが、この HTTPClient 3.1 には Content-Type で指定する以外の文字コード指定方法はありません（ NameValuePair 配列で指定した本文がどのような内部処理をされているのかはわかりません。。）　というわけで、この方法も詰み・・・

結論として、HTTPClient のバージョンをより新しいものに上げて対処しました。現在の最新バージョンは 4.5.2 のようです（僕は 4.5.1 を使いました）：
https://hc.apache.org/httpcomponents-client-ga/

このライブラリに置き換えた上で、コードも以下のように 4.5.x 仕様に書き換えました（完成版です）：

  :
public int sendMail( String to, String subject, String html ){
  int r = 0;

  try{
    PostMethod method = new PostMethod( "https://api.sendgrid.com/api/mail.send.json" );
    method.setRequestHeader( "Authorization", "Bearer SG.*****" );
    List<namevaluepair> params = new ArrayList<namevaluepair>();
    params.add( new BasicNameValuePair( "to", to ) );
    params.add( new BasicNameValuePair( "from", "info@from.com" ) );
    params.add( new BasicNameValuePair( "subject", subject ) );
    params.add( new BasicNameValuePair( "html", html ) );
    method.setEntity( new UrlEncodedFormEntity( params, "UTF-8" ) );
    CloseableHttpClient client = HttpClients.createDefault();
    CloseableHttpResponse response = client.execute( method );
    int sc = response.getStatusLine().getStatusCode();
    HttpEntity entity = response.getEntity();
    String json = EntityUtils.toString( entity, StandardCharsets.UTF_8 );
      :
    r = 1;
  }catch( Exception e ){
    mothod.setRequest
    e.printStackTrace();
    r = -1;
  }

  return r;
}
  :

この関数は期待通りに動き、実行後にメールを受け取ると、期待通りの HTML コンテンツが文字化けなしに表示されました：



と、偉そうに書きましたが、実の所、なぜ前の２つのコードで動かないのかわかりません。最新コードでは NameValuePair 配列を UTF-8 指定で追加していて、これは旧バージョンにはない関数なので、その差で文字化けの有無になっているのかもしれません。ただ繰り返しますが、curl では最小限の指定だけで動いていたことと同じ指定をしているのに、Java でうまく動かない理由が説明できないのでした（少なくともエラーメッセージの内容をそのまま信用して対処しようとするとハマりそうな予感・・・）。

まあとりあえずは結果オーライ、ということで。あと SendGrid のメール送信を Java から、それも SDK ではなく Web API 経由で送る例はあまり見かけることがなかったので、後からやる人の助けになれば嬉しいです。

タグ ：

#sendgrid

#api

#mail

#send

#rest