Forem: nikaera

[TECH] OpenNext + Drizzle で Cloudflare D1 環境を最も楽に構築する 🌧️

nikaera — Sat, 02 Aug 2025 06:55:21 +0000

はじめに

OpenNext + Cloudflare D1 を使った開発で、ローカル環境での開発・テスト・本番への移行を効率的に行いたいと考えたことはありませんか。

愚直に実現しようとすると、環境ごとに異なる設定ファイルを用意したり、テストデータの管理に手間がかかります。Drizzle のエコシステム（drizzle-orm、drizzle-kit、drizzle-seed）を活用することで、これらの課題を解決し、シームレスな開発体験を実現する方法を紹介します。

この記事では、実際の @opennextjs/cloudflare プロジェクト構成を参考に、ローカル開発からテスト実装、本番デプロイまでの一連の流れを解説します。

動作環境

{
  "dependencies": {
    "@libsql/client": "^0.15.10",
    "@opennextjs/cloudflare": "^1.6.2",
    "drizzle-orm": "^0.44.4"
  },
  "devDependencies": {
    "drizzle-kit": "^0.31.4",
    "drizzle-seed": "^0.3.1",
    "vitest": "^3.2.4",
    "wrangler": "^4.26.1"
  }
}

プロジェクト構成

この記事で構築する最終的な関連したプロジェクト構造は以下のようになります。

./
├── drizzle/
│   ├── migrations/           # マイグレーションファイルの格納先
│   │   └── 0000_init.sql
│   └── schema.ts            # データベーススキーマの定義
├── tests/
│   ├── db.test.ts           # drizzle-seed を使ったテスト
│   └── db.ts                # テスト用 DB のユーティリティ
├── drizzle.config.ts        # 各種 DB の設定ファイル
├── wrangler.jsonc           # Cloudflare Workers 設定 (D1)
└── package.json

1. 必要なパッケージのインストール

まず、必要なパッケージをインストールします。

npm install drizzle-orm @libsql/client
npm install -D drizzle-kit drizzle-seed vitest

2. Cloudflare D1 の設定

wrangler.jsonc に D1 データベースの情報を追記します。

<your-database-name> と <your-database-id> には、D1 データベースの「データベース名」と「データベースID」を指定します。値の確認・発行方法は後述します。

{
  "$schema": "node_modules/wrangler/config-schema.json",
  "name": "<your-app-name>",
  "main": ".open-next/worker.js",
  "compatibility_date": "2025-03-01",
  "compatibility_flags": ["nodejs_compat", "global_fetch_strictly_public"],
  // Cloudflare D1 データベースの情報
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "<your-database-name>",
      "database_id": "<your-database-id>",
      "migrations_dir": "drizzle/migrations"
    }
  ]
}

値の確認・発行方法

Cloudflare ダッシュボードから確認
- Cloudflare Dashboard にログインし、対象アカウントの「ストレージとデータベース」→「D1 SQL データベース」へ移動する
- 作成済みのデータベース一覧から、該当データベースを選択する
- <your-database-name> は一覧や詳細画面での表示名
  - 例: my-app-dev
- <your-database-id> は詳細画面の「UUID」
  - 例: e216461a-74c3-40b2-8819-9fa351827304

Wrangler CLI で新規作成する場合

下記コマンド成功時に出力される JSON フィールドの値を用いる
- database_name が <your-database-name>
- database_id が <your-database-id>

npx wrangler d1 create my-app-dev
# ...
Successfully created DB 'my-app-dev' in region APAC
Created your new D1 database.

{
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "my-app-dev",
      "database_id": "e216461a-74c3-40b2-8819-9fa351827304"
    }
  ]
}

これらの値を wrangler.jsonc の該当箇所にコピー&ペーストしてください。

3. 環境別のデータベース設定

drizzle.config.ts に本番環境とローカル環境の設定を記載します。

環境の切り分けには NODE_ENV 環境変数を利用しており、

NODE_ENV=production の場合は本番用、そうでない場合はローカル用の設定が適用されます。

import { readdirSync } from "fs"
import { defineConfig } from 'drizzle-kit'

const isProduction = process.env.NODE_ENV === 'production';
// `sqliteDirPath` は、wrangler で D1 環境を設定し、`dev` コマンドを実行した際に
// SQLite ファイルが生成されるディレクトリパスを指します。
const sqliteDirPath = '.wrangler/state/v3/d1/miniflare-D1DatabaseObject';
const sqliteFilePath = readdirSync(sqliteDirPath).find(file => file.endsWith('.sqlite'));

const config = isProduction ? defineConfig({
  out: './drizzle/migrations',
  schema: './drizzle/schema.ts',
  dialect: 'sqlite',
  driver: 'd1-http',
  dbCredentials: {
    accountId: process.env.CLOUDFLARE_ACCOUNT_ID!,
    databaseId: process.env.CLOUDFLARE_DATABASE_ID!,
    token: process.env.CLOUDFLARE_D1_TOKEN!,
  }
}) : defineConfig({
  out: './drizzle/migrations',
  schema: './drizzle/schema.ts',
  dialect: 'sqlite',
  dbCredentials: {
    url: `${sqliteDirPath}/${sqliteFilePath!}`,
  }
});

export default config;

wrangler のバージョンや環境によっては、SQLite ファイルの生成先ディレクトリが .wrangler/state/v3/d1/miniflare-D1DatabaseObject ではなく、.wrangler 配下の異なるパスになる可能性があります。

.wrangler 配下の SQLite ファイルのパスが不明な場合は、find コマンドで検索し特定できます。たとえば、以下のように実行すると、.sqlite 拡張子のファイルを探せます。

find .wrangler -type f -name "*.sqlite"

Cloudflare D1 の本番環境の設定には、以下の環境変数が必要です。

CLOUDFLARE_ACCOUNT_ID
CLOUDFLARE_DATABASE_ID
CLOUDFLARE_D1_TOKEN

本番環境設定の取得方法に関しては下記を参考にしてください。

https://zenn.dev/arafipro/articles/2024-07-24-drizzle-d1-table#drizzle.config.ts-1

4. データベーススキーマの定義

drizzle/schema.ts で以下の2つのテーブルを定義します。

conversations テーブル

チャットの会話単位を管理するテーブル
messages テーブル

各会話に紐づくメッセージを管理するテーブル、

conversationId で conversations テーブルとリレーションする。

import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core';
import { sql } from 'drizzle-orm';

export const conversations = sqliteTable('conversations', {
  id: text('id').primaryKey(),
  title: text('title'),
  createdAt: integer('created_at', { mode: 'timestamp' })
    .notNull()
    .default(sql`(unixepoch())`),
  updatedAt: integer('updated_at', { mode: 'timestamp' })
    .notNull()
    .default(sql`(unixepoch())`),
});

export const messages = sqliteTable('messages', {
  id: text('id').primaryKey(),
  conversationId: text('conversation_id')
    .notNull()
    .references(() => conversations.id, { onDelete: 'cascade' }),
  role: text('role', { enum: ['user', 'system'] }).notNull(),
  content: text('content').notNull(),
  createdAt: integer('created_at', { mode: 'timestamp' })
    .notNull()
    .default(sql`(unixepoch())`),
});

5. テスト環境の構築

tests/db.ts でテスト用のユーティリティ関数を作成します。テスト用データベースの作成・マイグレーションの適用・テストデータの投入などを行う関数をまとめています。

import { createClient } from '@libsql/client/node';
import { drizzle } from 'drizzle-orm/libsql';
import * as schema from '../drizzle/schema';
import { readFileSync } from 'fs';
import { join } from 'path';
import { seed, reset } from 'drizzle-seed';

export async function createTestDatabase() {
  const client = createClient({ url: ':memory:' });
  const db = drizzle(client, { schema });

  // `drizzle-kit` で生成された、実際のマイグレーションファイルを読み込む
  const migrationsDir = join(process.cwd(), 'drizzle/migrations');
  const migrationFiles = (
    await Promise.resolve(
      require('fs').readdirSync(migrationsDir)
        .filter((file: string) => file.endsWith('.sql'))
        .sort()
    )
  );

  // 正しい順序で逐次マイグレーションファイルを実行する
  for (const file of migrationFiles) {
    const migrationSQL = readFileSync(join(migrationsDir, file), 'utf-8');
    const statements = migrationSQL
      .split('--> statement-breakpoint')
      .map(stmt => stmt.trim())
      .filter(stmt => stmt.length > 0);

    for (const statement of statements) {
      await client.execute(statement);
    }
  }

  return { client, db };
}

export async function seedTestDataWithDrizzleSeed(
  db: any, 
  options?: { count?: number; seed?: number }
) {
  const { count = 3, seed: seedValue = 12345 } = options || {};

  // `drizzle-seed` の `refine` でテスト時に利用するシードデータを生成
  await seed(db as any, schema, { count, seed: seedValue }).refine((f) => ({
    conversations: {
      count: 3,
      columns: {
        title: f.valuesFromArray({
          values: [
            'AI System Chat',
            'Technical Q&A Session', 
            'Creative Writing Help',
            'Code Review Discussion',
            'Product Planning Talk'
          ]
        }),
      }
    },
    messages: {
      count: 6,
      columns: {
        role: f.valuesFromArray({
          values: ['user', 'system']
        }),
        content: f.valuesFromArray({
          values: [
            'Hello! How can you help me today?',
            'I\'m an AI system, happy to help with various tasks!',
            'Can you explain how TypeScript interfaces work?',
            'TypeScript interfaces define the shape of objects...',
            'What are the best practices for React development?',
            'Some key React best practices include using functional components...',
          ]
        }),
      }
    }
  }));

  return db;
}

export async function resetDatabase(db: any) {
  await reset(db as any, schema);
}

6. テストの実装

tests/db.test.ts で実際のテストを実装します。このテストで、データベースの接続やクエリ、モデルの動作や挙動などが正しく機能するかどうかを検証します。

import { describe, it, expect, beforeEach, afterEach } from 'vitest';
import { conversations, messages } from '../drizzle/schema';
import { eq } from 'drizzle-orm';
import { 
  createTestDatabase,
  seedTestDataWithDrizzleSeed, 
  resetDatabase 
} from './db';

describe('Drizzle Seed Test', () => {
  let client: any;
  let db: any;

  beforeEach(async () => {
    const testDb = await createTestDatabase();
    client = testDb.client;
    db = testDb.db;
  });

  afterEach(() => {
    client.close();
  });

  it('should seed test data using drizzle-seed', async () => {
    await seedTestDataWithDrizzleSeed(db, { count: 3, seed: 12345 });

    // 会話データの検証
    const allConversations = await db.select().from(conversations);
    expect(allConversations.length).toBeGreaterThan(0);

    // メッセージデータの検証
    const allMessages = await db.select().from(messages);
    expect(allMessages.length).toBeGreaterThan(0);

    // 外部キー制約の検証
    for (const message of allMessages) {
      const conversation = allConversations.find((c: any) => 
        c.id === message.conversationId
      );
      expect(conversation).toBeDefined();
    }

    // ロール値の検証
    for (const message of allMessages) {
      expect(['user', 'system']).toContain(message.role);
    }
  });

  it('should reset database correctly', async () => {
    await seedTestDataWithDrizzleSeed(db);

    let allConversations = await db.select().from(conversations);
    expect(allConversations.length).toBeGreaterThan(0);

    await resetDatabase(db);

    allConversations = await db.select().from(conversations);
    const allMessages = await db.select().from(messages);

    expect(allConversations).toHaveLength(0);
    expect(allMessages).toHaveLength(0);
  });
});

実際の開発フロー

予め package.json の scripts へ下記を登録しておきます。

{
  "scripts": {
    "test": "vitest run",
    "db:gen": "drizzle-kit generate",
    "db:mgn": "drizzle-kit migrate",
    "db:mgn:prd": "NODE_ENV=production drizzle-kit migrate",
    "db:client": "drizzle-kit studio"
  }
}

1. DB のローカル環境構築

# Wrangler dev でローカル開発環境を起動
npx wrangler dev

# 別ターミナルでマイグレーションを実行
npm run db:gen # 必要に応じて `-- --name <ファイル名>`
npm run db:mgn

# 適宜 DB 絡むテストを実行
npm test

Drizzle には、Drizzle Studio という GUI で DB を確認可能なツールが存在します。

Drizzle Studio は下記コマンドで起動可能です。

# DB クライアント (Drizzle Studio) の起動
npm run db:client

2. DB の本番環境への反映

# 本番環境でのマイグレーション
npm run db:mgn:prd

正常にコマンド実行が成功すれば、Cloudflare Dashboard の「D1 SQL データベース」から /tables コマンドで生成されたテーブルが確認できるはずです。

まとめ

Drizzle のエコシステムを活用することで、OpenNext + Cloudflare D1 を使った開発・テスト・本番環境をシームレスに構築できました。

OpenNext を利用したい動機として、複雑な設定や環境構築に時間を取られることなく、迅速かつ効率的にアプリケーションの実装を進めたいというモチベで採用されることが大半だと考えます。

本記事の手法を使うことで、データベース周りの煩雑な設定や運用から解放されます。

そのため、アプリケーションロジックの実装に集中できます。爆速で開発を進めていきましょう。

参考リンク

[IDEA] Flutter で本格的な HTTP キャッシュライブラリ「AeroCache」を作ってみた ☁️

nikaera — Sun, 13 Jul 2025 06:29:16 +0000

はじめに

Flutter は既存のキャッシュライブラリに HTTP のプライベートキャッシュに準拠したものが少なく、想定と異なる挙動により意図した形でキャッシュが更新されない状況に遭遇することが多々あります。例えば、Varyに未対応であったり、キャッシュ再検証周りのロジックが独自実装だったりが該当します。

そこで、RFC 9111 に準拠したキャッシュライブラリ AeroCache を開発しました。この記事では、その実装過程で学んだ HTTP のプライベートキャッシュに関する知識を簡潔に解説しつつ AeroCache を紹介します。

https://nikaera.com/aero_cache/

HTTP のプライベートキャッシュの仕組み

主にパフォーマンス向上や帯域節約、細やかなキャッシュ管理を実現するための仕組みとして、活用されるヘッダは以下の通りです。

ヘッダー	説明
Cache-Control	レスポンスキャッシュの有効期限や再検証ルールを指示するディレクティブ群、`max-age` や `no-cache` などが代表的
ETag	レスポンスごとに発行される一意の識別子、クライアントは `ETag` を使って「内容が変わったか」を効率的に判定可能
Last-Modified	レスポンスの最終更新日時、`If-Modified-Since` ヘッダーと組み合わせて、キャッシュの更新判定に利用される
Vary	`Accept-Language` や `User-Agent` などを指定することで、端末やリクエストごとに異なるキャッシュを保持可能

以降では、各要素の具体的な動作について詳しく解説します。

主要な `Cache-Control` ディレクティブの対応

HTTP レスポンスヘッダーの Cache-Control は、キャッシュ動作を制御する重要な仕組みです。
プライベートキャッシュの Cache-Control で用いられる主要なディレクティブは以下です。

ディレクティブ	説明
`max-age=N`	N秒間キャッシュを有効とみなす
`min-fresh=N`	有効期限よりもN秒以上最新のデータのみ許容
`max-stale[=N]`	有効期限切れN秒以内なら古いキャッシュ許容（N省略時は無制限）
`stale-while-revalidate=N`	有効期限切れN秒以内なら古いキャッシュ返却、裏側で更新処理
`stale-if-error=N`	エラー時はN秒間古いキャッシュで代替
`must-revalidate`	期限切れ時は必ずキャッシュの再検証
`no-cache`	使用前に必ずキャッシュの再検証
`no-store`	キャッシュしない（毎回ダウンロード）
`only-if-cached`	ネットワークアクセスせずキャッシュのみ利用

Cache-Control: max-age=600, stale-while-revalidate=3600

上記の設定では、以下のような動作になります。

最初の600秒間はキャッシュを新鮮とみなして即座に返す
600秒経過後、3600秒までは古いデータを返しつつバックグラウンドで更新
ユーザーは常に高速なレスポンスを得られる

特に stale-while-revalidate は、ユーザー体験とパフォーマンスの両立を実現する強力なキャッシュ戦略です。新しいデータの取得は裏側で自動的に行われるため、ユーザーは操作を中断することなく最新のデータが利用可能になります。

AeroCache はブラウザの挙動を強く意識しており、上記ディレクティブは全てサポートしています。ユーザーや開発者がキャッシュに関する挙動に悩まされないよう、独自ロジックなども極力排除しています。

ETag や Last-Modified による効率的な再検証

# 初回レスポンス
HTTP/1.1 200 OK
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
Cache-Control: max-age=3600

# 再検証リクエスト
GET /api/data HTTP/1.1
If-None-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"

# 変更なしの場合
HTTP/1.1 304 Not Modified

ETag や Last-Modified の利点は以下の通りです。

キャッシュが有効な場合
- クライアントはキャッシュをそのまま返却
キャッシュ期限切れの場合
- クライアントは ETag/Last-Modified を付与して再検証リクエストを送信
- データに変更無ければ 304 Not Modified を返し、キャッシュを再利用
- データに変更があれば新しいデータを返却し、キャッシュを更新

この仕組みにより、無駄なデータ転送を防ぎつつ常に最新データを効率的に取得できます。

再検証周りのロジックが独自実装のライブラリは、再起動しない限りキャッシュが更新されなかったりします。AeroCache ではそのような挙動は発生しません。

Vary による条件付きキャッシュ

レスポンスがリクエストヘッダーに依存する場合の重要な仕組みです。

HTTP/1.1 200 OK
Vary: Accept-Language, User-Agent
Content-Language: ja
Cache-Control: max-age=3600

この例では、Accept-Language と User-Agent の値が異なるリクエストは、別々にキャッシュされます。

Vary ヘッダーはキャッシュの粒度を柔軟に制御できる仕組みです。例えば、言語やデバイスごとに異なるレスポンスを返す API では、Vary を使うことで下記のように「リクエストヘッダーごとに別々のキャッシュ」を作成できます。

多言語対応: Accept-Language を指定すれば、ユーザーの言語ごとに最適なキャッシュを保持
デバイス最適化: User-Agent を使えば、デバイス間で異なるレスポンスをキャッシュ可能
パーソナライズ: Cookie や Authorization など、個別ユーザー向けキャッシュも実現可能

AeroCache では Vary を考慮した設計となっており Vary でキャッシュコントロールが可能です。

おわりに

実業務で悩まされてきた問題に終止符を打つべく開発した AeroCache について紹介しました。

標準仕様に沿ったキャッシュ管理で予期せぬ不具合や運用負荷を減らし、安心して利用できる HTTP キャッシュライブラリを目指しました。今後も実運用で得られた知見やフィードバックをもとに、より使いやすく信頼性の高いライブラリへと改善を続けていきます。

また、現状は利便性向上のための追加実装として下記を検討しています。

cached_network_image の AeroCache 版
HTTP クライアントの Interceptor 開発 (dio, http, etc.)
コンテンツに影響しない URL パラメータのブラックリスト対応
コンテンツ毎の可逆圧縮有無の設定, etc.

参考リンク

[TECH] ECS Fargate のメトリクスを Prometheus Agent 使って AMP に送って Grafana で監視する 🔥

nikaera — Mon, 06 Dec 2021 02:05:38 +0000

はじめに

この記事は AWS Advent Calendar 2021 の 5 日目の記事です。

Fargate で Node.js アプリのメトリクスを Prometheus Agent をサイドカーコンテナとして動かして、Amazon Managed Service for Prometheus (AMP) に送信して Grafana で見られるようにしてみました。

ちなみに Promethus Agent はまだ実験的な機能なため、実務での利用は推奨しません。

本記事の環境構築には AWS CDK を利用しています。

動作環境

Node.js v16.13.0
AWS CDK 2.0.0 (build 4b6ce31)
Prometheus 2.32.1

環境構築

早速環境構築を進めていきます。まだ AMP については CDK から操作できないようでしたので、ワークスペースの作成については AWS コンソールから手動で行います。(2021/12/06)

aws-aps を利用することで AWS CDK からでも Amazon Managed Service for Prometheus のワークスペースを作成すること確認できましたので、そちらの利用を推奨いたします... 🙇🙇

lib/prometheus-agent-test-stack.ts のコードも修正済みで AWS CDK で Amazon Managed Service for Prometheus のワークスペースを作成するように編集しました。(2021/12/18 追記)

まず、AMP のコンソール画面に遷移してワークスペースを作成します。

1. AMP のコンソール画面からワークスペース作成画面に遷移する

2. AMP のワークスペースを作成する

3. AMP のワークスペース作成完了を確認すると同時に設定値を控えておく

AMP ワークスペースの エンドポイント - リモート書き込み URL は、Prometheus Agent で AMP にデータ送信する際や、Grafana でデータソースを登録する際などに必要となるため控えておきます。

AWS CDK で環境構築する

CDK で構築作業を進めます。まずは下記コマンドで CDK プロジェクトを作成します。使用言語は TypeScript を選択します。

mkdir prometheus-agent-test && cd prometheus-agent-test
cdk init --language typescript

まず CDK でインフラ構築を進めていく前に、メトリクス収集テスト用の Node.js アプリを準備します。

ECS Fargate で動かす Node.js アプリを準備する

prom-client を利用して、Node.js のメトリクスが取得できるだけの Node.js アプリを準備します。prometheus-agent-test フォルダで下記コマンドを実行します。

mkdir metrics-app && cd metrics-app
npm init -y
npm install --save prom-client

次に metrics-app フォルダ内に index.js を作成して下記を編集します。

'use strict';

const http = require('http');
const server = http.createServer();

const client = require('prom-client');
const register = new client.Registry()

// 5秒間隔でメトリクスを取得する
client.collectDefaultMetrics({ register, timeout: 5 * 1000 });

server.on('request', async function(req, res) {
    // /metrics にアクセスしたら、Prometheus のレポートを返す
    if (req.url === '/metrics') {
        res.setHeader('Content-Type', register.contentType)

        const metrics = await register.metrics()
        return res.end(metrics)
    } else {
        return res.writeHead(404, {'Content-Type' : 'text/plain'});
    }
});

server.listen(8080);

node index.js コマンドを実行して http://localhost:8080/metrics にアクセスしてみます。下記のように各種メトリクスが出力されている様子が確認できれば OK です。

Prometheus のレポートが正常に出力されている様子

今回は ECS 上で Node.js アプリを動作させるため、Dockerfile も作成します。

FROM public.ecr.aws/docker/library/node:16-alpine3.12 AS builder

EXPOSE 8080
WORKDIR /usr/src/app

COPY package*.json ./
RUN npm install --max-old-space-size=4096

COPY . .

CMD [ "node", "index.js" ]

上記 Dockerfile 作成後、再び動作検証のため下記コマンドを実行してから、http://localhost:8080/metrics にアクセスしてみます。

docker build -t prometheus-agent-test/metrics-app .
docker run -p 8080:8080 prometheus-agent-test/metrics-app:latest

先ほどと同様に http://localhost:8080/metrics アクセス時に各種メトリクスが出力されている様子を確認できれば OK です。

Node.js アプリを監視する Prometheus Agent を準備する

まずは Prometheus 関連ファイルを配置するためのフォルダを作成します。prometheus-agent-test フォルダ内で下記コマンドを実行します。

mkdir prometheus-agent && cd prometheus-agent

次に Prometheus の設定テンプレートファイルを作成します。テンプレートファイルは sed を利用して中身の __TASK_ID__ および __REMOTE_WRITE_URL__ を書き換えて利用します。

global:
  scrape_interval: 5s
  external_labels:
    monitor: 'prometheus'

scrape_configs:
  - job_name: 'prometheus-agent-test'
    static_configs:
      - targets: ['localhost:8080']
        labels:
          # デフォルトの localhost:8080 がインスタンスとして利用されると、
          # メトリクスの判別がしづらくなるため ECS Task の ID を利用する
          instance: '__TASK_ID__'

remote_write:
  # AMP ワークスペース作成時に控えておいた、
  # `エンドポイント - リモート書き込み URL` を設定する箇所
  - url: '__REMOTE_WRITE_URL__'
    sigv4:
      region: ap-northeast-1
    queue_config:
      max_samples_per_send: 1000
      max_shards: 200
      capacity: 2500

設定ファイルの作成が完了したら、テンプレートファイルを利用して Prometheus の設定ファイルを作成し、Prometheus Agent を起動させるためのシェルスクリプトを作成します。

#!/bin/sh

while [ -z "$taskId" ]
do
  # ECS Fargate で起動したタスク ID を取得する
  taskId=$(curl --silent ${ECS_CONTAINER_METADATA_URI}/task | jq -r '.TaskARN | split("/") | .[-1]')

  echo "waiting..."
  sleep 1
done

echo "taskId: ${taskId}"
echo "remoteWriteUrl: ${REMOTE_WRITE_URL}"

# タスク ID `taskId` および、環境変数 `REMOTE_WRITE_URL` で、
# Prometheus のテンプレートファイル `prometheus.tmpl.yml` の内容を書き換え、
# その結果を `/etc/prometheus/prometheus.yml` に出力する
cat /etc/prometheus/prometheus.tmpl.yml | \
    sed "s/__TASK_ID__/${taskId}/g" | \
    sed "s>__REMOTE_WRITE_URL__>${REMOTE_WRITE_URL}>g" > /etc/prometheus/prometheus.yml

# --enable-feature=agent で Prometheus を Agent モードで起動する
# Prometheus のコンフィグファイルには上記で出力した `/etc/prometheus/prometheus.yml` を利用する
/usr/local/bin/prometheus \
    --enable-feature=agent \
    --config.file=/etc/prometheus/prometheus.yml \
    --web.console.libraries=/etc/prometheus/console_libraries \
    --web.console.templates=/etc/prometheus/consoles

これで Prometheus Agent 起動のための準備は整ったため、最後に Dockerfile を準備します。ちなみに Prometheus Agent は v2.32.0 以降で利用可能です。本記事では v2.32.1 を利用します。

FROM --platform=arm64 alpine:3.15

ADD prometheus.tmpl.yml /etc/prometheus/

RUN apk add --update --no-cache jq sed curl

# ARM64 で動作する Prometheus v2.32.1 を curl でダウンロード展開する
RUN curl -sL -O https://github.com/prometheus/prometheus/releases/download/v2.32.1/prometheus-2.32.1.linux-arm64.tar.gz
RUN tar -zxvf prometheus-2.32.1.linux-arm64.tar.gz && rm prometheus-2.32.1.linux-arm64.tar.gz

# `prometheus` コマンドを `/usr/local/bin/prometheus` に移動する
RUN mv prometheus-2.32.1.linux-arm64/prometheus /usr/local/bin/prometheus

COPY ./docker-entrypoint.sh /
RUN chmod +x /docker-entrypoint.sh
CMD ["/docker-entrypoint.sh"]

ここまでで CDK でインフラ整備を進めていくための下準備は完了です。

ECS Fargate 上で Node.js アプリおよび Prometheus Agent を動作させる

あとは CDK で ECS Fargate 上で Node.js アプリおよび Prometheus Agent、Grafana を動作させるための環境を整備していきます。

lib/prometheus-agent-test-stack.ts の内容を書き換えます。

import { Construct } from 'constructs';
import {
  Stack,
  StackProps,
  aws_ecs as ecs,
  aws_logs as logs,
  aws_aps as aps,
  aws_ecs_patterns as ecs_patterns,
  aws_iam as iam,
  aws_elasticloadbalancingv2 as elbv2,
  Duration,
  CfnOutput,
} from 'aws-cdk-lib';

export class PrometheusAgentTestStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    // Node.js アプリに ecs_patterns.ApplicationLoadBalancedFargateService を利用して ALB 経由でアクセス可能にする
    const projectName = 'prometheus-agent-test';
    const fargateService = new ecs_patterns.ApplicationLoadBalancedFargateService(this, `${projectName}-fargate-service`, {
      serviceName: `${projectName}-fargate-service`,
      cpu: 256,
      desiredCount: 3,
      listenerPort: 80,
      taskImageOptions: {
        family: `${projectName}-taskdef`,
        image: ecs.ContainerImage.fromAsset('metrics-app'),
        containerPort: 8080,
        logDriver: ecs.LogDrivers.awsLogs({
          streamPrefix: `/${projectName}/metrics-app`,
          logRetention: logs.RetentionDays.ONE_DAY
        })
      },
      cluster: new ecs.Cluster(this, `${projectName}-cluster`, {
        clusterName: `${projectName}-cluster`
      }),
      memoryLimitMiB: 512,
    });
    fargateService.targetGroup.configureHealthCheck({
      path: "/metrics",
      timeout: Duration.seconds(8),
      interval: Duration.seconds(10),
      healthyThresholdCount: 2,
      unhealthyThresholdCount: 4,
      healthyHttpCodes: "200",
    });

    // 本質ではないが、Gravition2 で動作させたいために RuntimePlatform のプロパティを上書きしている
    const fargateServiceTaskdef = fargateService.taskDefinition.node.defaultChild as ecs.CfnTaskDefinition
    fargateServiceTaskdef.addPropertyOverride('RuntimePlatform', {
      CpuArchitecture: "ARM64",
      OperatingSystemFamily: "LINUX"
    });

    // AMP への書き込み権限を付与する
    fargateService.taskDefinition.taskRole.addManagedPolicy(
      iam.ManagedPolicy.fromAwsManagedPolicyName('AmazonPrometheusRemoteWriteAccess')
    )

    // (2021/12/18) Amazon Managed Service for Prometheus のワークスペースを作成して、Prometheus の remote-write URL を取得する
    const apsWorkspace = new aps.CfnWorkspace(this, `${projectName}-prom-workspace`, {
      alias: `${projectName}-prom-workspace`,
    });
    const apsWorkspaceRemoteUrl = `${apsWorkspace.attrPrometheusEndpoint}api/v1/remote_write`;

    // (2021/12/18) 本記事で頻出する "エンドポイント - リモート書き込み URL" をコンソールに出力する
    new CfnOutput(this, 'prom-remote-write-url', {
      value: apsWorkspaceRemoteUrl,
      description: 'Prometheus Workspace の remote-write URL',
      exportName: 'PromRemoteWriteURL',
    });

    // AMP へメトリクス情報を送信するための Prometheus Agent コンテナを追加する
    const containerName = `${projectName}-prometheus-agent`
    fargateService.taskDefinition.addContainer(containerName, {
      containerName,
      image: ecs.ContainerImage.fromAsset('prometheus-agent'),
      memoryReservationMiB: 128,
      environment: {
        // (2021/12/18) CDK 経由で作成した Prometheus の remote-write URL を設定する
        REMOTE_WRITE_URL: apsWorkspaceRemoteUrl
      },
      logging: new ecs.AwsLogDriver({
        streamPrefix: `/${projectName}/prometheus-agent`,
        logRetention: logs.RetentionDays.ONE_DAY,
      })
    });

    // Grafana のタスク定義を作成する
    const grafanaDashboardTaskDefinition = new ecs.FargateTaskDefinition(this, `${projectName}-grafana-taskdef`, {
      family: `${projectName}-grafana-taskdef`
    });
    // Grafana のタスクが Prometheus Query を叩けるように権限付与する
    grafanaDashboardTaskDefinition.taskRole.addManagedPolicy(
      iam.ManagedPolicy.fromAwsManagedPolicyName('AmazonPrometheusQueryAccess')
    )

    // Grafana のコンテナを追加する。パスプレフィクスには dashboard を設定する
    const grafanaDashboardContainerName = `${projectName}-grafana-dashboard`
    grafanaDashboardTaskDefinition.addContainer(grafanaDashboardContainerName, {
      containerName: grafanaDashboardContainerName,
      image: ecs.ContainerImage.fromRegistry('public.ecr.aws/ubuntu/grafana'),
      environment: {
        AWS_SDK_LOAD_CONFIG: 'true',
        GF_AUTH_SIGV4_AUTH_ENABLED: 'true',
        GF_SERVER_SERVE_FROM_SUB_PATH: 'true',
        GF_SERVER_ROOT_URL: '%(protocol)s://%(domain)s/dashboard'
      },
      portMappings: [{ containerPort: 3000 }],
      memoryLimitMiB: 512,
      logging: new ecs.AwsLogDriver({
        streamPrefix: `/${projectName}/grafana-dashboard`,
        logRetention: logs.RetentionDays.ONE_DAY,
      })
    });

    const grafanaDashboardServiceName = `${projectName}-grafana-dashboard-service`
    const grafanaDashboardService = new ecs.FargateService(this, grafanaDashboardServiceName, {
      serviceName: grafanaDashboardServiceName,
      cluster: fargateService.cluster,
      taskDefinition: grafanaDashboardTaskDefinition,
      desiredCount: 1
    });

    // Grafana のタスクを ALB のターゲットグループに紐づける
    fargateService.listener.addTargets(`${projectName}-grafana-dashboard-target`, {
      priority: 1,
      conditions: [
        elbv2.ListenerCondition.pathPatterns(['/dashboard/*']),
      ],
      healthCheck: {
        path: '/dashboard/login',
        interval: Duration.seconds(10),
        timeout: Duration.seconds(8),
        healthyThresholdCount: 2,
        unhealthyThresholdCount: 3,
        healthyHttpCodes: "200"
      },
      port: 3000,
      protocol: elbv2.ApplicationProtocol.HTTP,
      targets: [grafanaDashboardService],
    });
  }
}

その後、cdk deploy でインフラを構築します。

CDK によるインフラ構築が正常に実行された時の様子

デプロイが正常に完了したのを確認したら、Outputs に出力されている PrometheusAgentTestStack.prometheusagenttestfargateserviceServiceURL<識別子> の URL 末尾に /metrics を付与してアクセスしてみます。 出力されている URL のフォーマットは http://<識別子>.ap-northeast-1.elb.amazonaws.com になります。

つまり、http://<識別子>.ap-northeast-1.elb.amazonaws.com/metrics にアクセスします。

ALB 経由で Node.js アプリにアクセス可能なことを確認する

また、Outputs に出力されている PrometheusAgentTestStack.promremotewriteurl は後に利用する エンドポイント - リモート書き込み URL で使用するので控えておきます。

ここまでで AWS CDK でのインフラ構築作業は完了しました。最後に Grafana で AMP のメトリクスを可視化するための作業を進めていきます。

Grafana で Prometheus (AMP) のメトリクスを可視化する

先ほどの /metrics パスへのアクセス同様、Outputs に出力されている URL の末尾に /dashboard/login を付与してアクセスします。Grafana の初期ユーザおよびパスワードは admin となります。

つまり、http://<識別子>.ap-northeast-1.elb.amazonaws.com/dashboard/login にアクセスしてみます。

ログイン情報が正しければ、新しいパスワードを設定する画面に遷移するので新たなパスワードを入力してログインを終えます。ログイン後は、Prometheus (AMP) をデータソースとして追加するために下記の操作を行います。

1. 歯車アイコンをクリックして Data sources をクリックする

2. Add data source ボタンをクリックする

3. データソースとして Prometheus を選択する

4. Prometheus をデータソースとして追加する

Prometheus (AMP) に送信したメトリクスを Grafana で可視化するための準備が整ったので、実際に Grafana のダッシュボードでメトリクスを可視化してみます。手っ取り早くメトリクスを可視化するため、ダッシュボードには NodeJS Application Dashboard を利用します。

1. + アイコンをクリックして、Import をクリックする

2. NodeJS Application Dashboard の ID を入力して Load ボタンをクリックする

3. 必要な情報を入力して NodeJS Application Dashboard のインポートを完了する

4. ダッシュボードから Node.js アプリのメトリクスが確認できる

ここまでの手順でメトリクスの可視化は完了しましたが、負荷に応じて実際にメトリクスが変化する様子も確認してみます。Vegeta を利用して、実際に負荷をかけてみます。下記コマンドを実行します。

echo 'GET http://<識別子>.ap-northeast-1.elb.amazonaws.com/metrics' | vegeta attack -duration=5s | vegeta report

その後、再び Grafana のダッシュボードを見にいきます。負荷をかけた時間帯のみグラフに変化があることを確認できるはずです。

ダッシュボードの CPU 使用率のグラフに変化があったことを確認できる

おわりに

今回は ECS Fargate のメトリクスを Prometheus Agent で Amazon Managed Service for Prometheus (AMP) に送信し、それを Grafana で可視化する方法について紹介しました。

ECS のサービスでタスクを実行する場合はサービスディスカバリの利用が可能なため、Prometheus のサービスディスカバリの設定を行うことで、単一の Prometheus で全てのコンテナのメトリクスを扱うことも可能です。

また Node.js アプリを作成する際に利用した prom-client でカスタムメトリクスを作成することで、監視したい項目を自由に増やすことも可能です。

本記事が ECS Fargate を監視する際の検討材料の 1 つとなれたら幸いです。

参考リンク

[TECH] Unity で iOS/Android アプリの設定値をセキュアに扱う方法 🔑

nikaera — Sun, 15 Aug 2021 15:46:39 +0000

はじめに

iOS/Android でユーザーの情報をセキュアに扱う必要があったので、調査したところ Android には EncryptedSharedPreferences が存在することを知りました。iOS には Keychain Services が存在します。

今回は Unity の iOS/Android プラットフォーム上で設定値を保存するための実装を行う必要があったので、Unity から扱えるようネイティブプラグインを作成しました。今後もこういった要望はありそうでしたので、記事として手順や内容を書き記しておくことにしました。

本記事内で紹介しているコードは下記にアップ済みです。

https://github.com/nikaera/Unity-iOS-Android-SecretManager-Sample

動作環境

MacBook Air (M1, 2020)
Unity 2020.3.15f2
Android 6.0 以上
- EncryptedSharedPreferences が使用可能なバージョン

Android のネイティブプラグインを作成する

Android 環境ではまず External Dependency Manager for Unity を利用して、Unity の Android ネイティブプラグインで EncryptedSharedPreferences 利用可能にします。

(追記) Gradle を利用したライブラリのインストール方法

shiena さんにご教授いただいたのですが、こちらの記事のように Gradle を利用することでも簡易にライブラリの取り込みが可能なようでした。

手順は上記の記事をご参照いただくとして、Gradle を利用する方法で外部ライブラリを取り込む際の Assets/Plugins/Android/mainTemplate.gradle および Assets/Plugins/Android/gradleTemplate.properties は下記になります。

```diff gradle
dependencies {
implementation fileTree(dir: 'libs', include: ['*.jar'])

implementation 'androidx.security:security-crypto:1.1.0-alpha03' DEPS}

android {






```diff properties
org.gradle.jvmargs=-Xmx**JVM_HEAP_SIZE**M
org.gradle.parallel=true
android.enableR8=**MINIFY_WITH_R_EIGHT**
+ android.useAndroidX=true
unityStreamingAssets=.unity3d**STREAMING_ASSETS**
**ADDITIONAL_PROPERTIES**

Gradle を利用した方法でライブラリを利用される際は、次の External Dependency Manager for Unity で必要なパッケージをインストールする の手順はスキップ可能です。EncryptedSharedPreferences を利用するためのネイティブコードを追加する のステップから進めてください。

External Dependency Manager for Unity を利用する方法だと、取り込み先プロジェクト内でライブラリの競合が発生する恐れがあります。Gradle を利用する方法であれば回避が可能です。¹

External Dependency Manager for Unity で必要なパッケージをインストールする

External Dependency Manager for Unity をインポートするため unitypackage をダウンロードして、EncryptedSharedPreferences を導入したい Unity プロジェクトを開いてから unitypackage をクリックすることで、External Dependency Manager for Unity を Unity プロジェクトにインポートします。

Unity プロジェクトの Build Settings からプラットフォームは Android に切り替えておきます。Enable Android Auto-resolution? というダイアログの選択肢はどちらを選んでも構いません。²

External Dependency Manager for Unity で各種パッケージを管理する方法は README に記載がある通り、*Dependencies.xml というファイルを Editor フォルダに配置することで可能になります。

今回は EncryptedSharedPreferences を導入するため、下記の xml ファイルを Editor フォルダ内に配置します。

<?xml version="1.0" encoding="utf-8"?>
<dependencies>
    <androidPackages>
        <!--
            本記事ではバージョン 1.1.0-alpha03 を利用している
        -->
        <androidPackage spec="androidx.security:security-crypto:1.1.0-alpha03">
            <androidSdkPackageIds>
                <!--
                    Google の Maven リポジトリからインストールするため、
                    extra-google-m2repository を指定する
                -->
                <androidSdkPackageId>extra-google-m2repository</androidSdkPackageId>
            </androidSdkPackageIds>
        </androidPackage>
    </androidPackages>
</dependencies>

その後、Unity メニューから Assets -> External Dependency Manager -> Android Resolver -> Force Resolve を選択して、Assets/Editor/AndroidPluginDependencies.xml の内容を元に EncryptedSharedPreferences を利用するのに必要なパッケージを自動で Assets/Plugins/Android フォルダにダウンロードします。

1. Unity メニューから Assets -> External Dependency Manager -> Android Resolver -> Force Resolve を選択する

2. 実行に成功すると EncryptedSharedPreferences を利用するのに必要なライブラリ群が Assets/Plugins/Android フォルダに配置される

ここまで来ればあとは Android ネイティブコードを Assets/Plugins/Android フォルダ内に配置して Unity 側から叩けるようにするだけです。

EncryptedSharedPreferences を利用するためのネイティブコードを追加する

早速下記の Android ネイティブコードを Assets/Plugins/Android/SecretManager.java に配置します。

package com.nikaera;

import com.unity3d.player.UnityPlayerActivity;

import java.lang.Exception;

// External Dependency Manager for Unity によって、
// 必要な jar が含まれているため EncryptedSharedPreferences の利用が可能になる
import androidx.security.crypto.EncryptedSharedPreferences;
import androidx.security.crypto.MasterKey;

import android.content.Context;
import android.content.SharedPreferences;
import android.content.SharedPreferences.Editor;

import android.os.Bundle;
import android.util.Log;

public class SecretManager {
  private SharedPreferences sharedPreferences;

  public SecretManager(Context context) {
    try {
        // EncryptedSharedPreferences で設定値を保存する際に用いる、
        // 暗号鍵を扱うためのラッパークラスをデフォルト設定で作成する
        MasterKey masterKey = new MasterKey.Builder(context)
                .setKeyScheme(MasterKey.KeyScheme.AES256_GCM)
                .build();

        // EncryptedSharedPreferences のインスタンスを生成する
        // コンストラクタで作成した masterKey を指定している
        this.sharedPreferences = EncryptedSharedPreferences.create(
          context, context.getPackageName(), masterKey,
          EncryptedSharedPreferences.PrefKeyEncryptionScheme.AES256_SIV,
          EncryptedSharedPreferences.PrefValueEncryptionScheme.AES256_GCM
        );
    } catch (Exception e) {
        e.printStackTrace();
    }
  }

  /**
   * 指定したキーで値を保存する関数
   * @param key 値を保存する際に用いるキー
   * @param value 保存したい値
   * @return boolean 値の保存に成功したかどうか
   */
  public boolean put(String key, String value) {
    SharedPreferences.Editor editor = sharedPreferences.edit();
    editor.putString(key, value);

    return editor.commit();
  }

  /**
   * 指定したキーで保存した値を取得する関数
   * `put` 関数で保存した値を取得するのに利用する
   * @param key 取得したい値のキー
   * @return string キーに紐づく値、存在しなければ空文字が返却される
   */
  public String get(String key) {
    return sharedPreferences.getString(key, null);
  }

  /**
   * 指定したキーで値を削除する関数
   * @param key 削除したい値のキー
   * @return boolean 値の削除に成功したかどうか
   */
  public boolean delete(String key) {
    SharedPreferences.Editor editor = sharedPreferences.edit();
    editor.remove(key);

    return editor.commit();
  }
}

その後、上記を Unity スクリプトから実行可能にするための C# クラスを作成します。本記事ではファイルを Assets/Scripts/EncryptedSharedPreferences.cs に配置します。

using UnityEngine;

/// <summary>
///     利用するネイティブコードは <c>Assets/Plugins/Android/SecretManager.java</c> に記載
/// </summary>
/// <remarks>
///     <a href="https://developer.android.com/reference/androidx/security/crypto/EncryptedSharedPreferences">EncryptedSharedPreferences</a>
/// </remarks>
class EncryptedSharedPreferences
{
    private readonly AndroidJavaObject _secretManager;
    public EncryptedSharedPreferences()
    {
        // コンストラクタで com.nikaera.SecretManager のインスタンス生成を行う
        var activity = new AndroidJavaClass("com.unity3d.player.UnityPlayer")
            .GetStatic<AndroidJavaObject>("currentActivity");
        var context = activity.Call<AndroidJavaObject>("getApplicationContext");
        _secretManager = new AndroidJavaObject("com.nikaera.SecretManager", context);
    }

    public bool Put(string key, string value)
    {
        return _secretManager.Call<bool>("put", key, value);
    }

    public string Get(string key)
    {
        return _secretManager.Call<string>("get", key);
    }

    public bool Delete(string key)
    {
        return _secretManager.Call<bool>("delete", key);
    }
}

あとは用途に応じて下記のようなコードで設定値の保存や取得などを行えます。

// ...
var _sharedPreferences = new EncryptedSharedPreferences();

// name をキーとして値を nikaera で保存する
_sharedPreferences.Put("name", "nikaera");

// name をキーとして値を取得する
var name = _sharedPreferences.Get("name");

// "nikaera" が出力される
Debug.Log(name);

//　name をキーとして値を削除する
_sharedPreferences.Delete("name");

// ...

iOS のネイティブプラグインを作成する

iOS の場合は外部ライブラリを利用しないため、External Dependency Manager for Unity は利用しません。本来であれば Swift で信頼できる外部フレームワークを取り込み利用できると良さそうですが、今回は Objective-C でネイティブプラグインを書いていきます。³

Keychain Services を利用するためのネイティブコードを追加する

早速下記の iOS ネイティブコードを Assets/Plugins/iOS/KeychainService.mm に配置します。

// Keychain Services を利用するために Security フレームワークを利用する
#import <Security/Security.h>

extern "C"
{
    // 指定したキーで値を保存する関数
    // - param
    //   - dataType:  値を保存する際に用いるキー
    //   - value: 保存したい値
    // - return
    //   - 保存時のステータスコードを返却する (0 以外は失敗)
    int addItem(const char *dataType, const char *value)
    {
        NSMutableDictionary* attributes = nil;
        NSMutableDictionary* query = [NSMutableDictionary dictionary];
        NSData* sata = [[NSString stringWithCString:value encoding:NSUTF8StringEncoding] dataUsingEncoding:NSUTF8StringEncoding];

        [query setObject:(id)kSecClassGenericPassword forKey:(id)kSecClass];
        [query setObject:(id)[NSString stringWithCString:dataType encoding:NSUTF8StringEncoding] forKey:(id)kSecAttrAccount];

        OSStatus err = SecItemCopyMatching((CFDictionaryRef)query, NULL);

        if (err == noErr) {
            attributes = [NSMutableDictionary dictionary];
            [attributes setObject:sata forKey:(id)kSecValueData];
            [attributes setObject:[NSDate date] forKey:(id)kSecAttrModificationDate];

            err = SecItemUpdate((CFDictionaryRef)query, (CFDictionaryRef)attributes);
            return (int)err;
        } else if (err == errSecItemNotFound) {
            attributes = [NSMutableDictionary dictionary];
            [attributes setObject:(id)kSecClassGenericPassword forKey:(id)kSecClass];
            [attributes setObject:(id)[NSString stringWithCString:dataType encoding:NSUTF8StringEncoding] forKey:(id)kSecAttrAccount];
            [attributes setObject:sata forKey:(id)kSecValueData];
            [attributes setObject:[NSDate date] forKey:(id)kSecAttrCreationDate];
            [attributes setObject:[NSDate date] forKey:(id)kSecAttrModificationDate];
            err = SecItemAdd((CFDictionaryRef)attributes, NULL);
            return (int)err;
        } else {
            return (int)err;
        }
    }

    // 指定したキーで値を取得する関数
    // - param
    //   - dataType: 値を取得する際に用いるキー
    // - return
    //   - キーに紐づく値、存在しなければ空文字が返却される
    char* getItem(const char *dataType)
    {
        NSMutableDictionary* query = [NSMutableDictionary dictionary];
        [query setObject:(id)kSecClassGenericPassword forKey:(id)kSecClass];
        [query setObject:(id)[NSString stringWithCString:dataType encoding:NSUTF8StringEncoding] forKey:(id)kSecAttrAccount];
        [query setObject:(id)kCFBooleanTrue forKey:(id)kSecReturnData];

        CFDataRef cfresult = NULL;
        OSStatus err = SecItemCopyMatching((CFDictionaryRef)query, (CFTypeRef*)&cfresult);

        if (err == noErr) {
            NSData* passwordData = (__bridge_transfer NSData *)cfresult;
            const char* value = [[[NSString alloc] initWithData:passwordData encoding:NSUTF8StringEncoding] UTF8String];
            char *str = strdup(value);
            return str;
        } else {
            return NULL;
        }
    }

    // 指定したキーで値を削除する関数
    // - param
    //   - dataType:  値を削除する際に用いるキー
    // - return
    //   - 保存時のステータスコードを返却する (0 以外は失敗)
    int deleteItem(const char *dataType)
    {
        NSMutableDictionary* query = [NSMutableDictionary dictionary];
        [query setObject:(id)kSecClassGenericPassword forKey:(id)kSecClass];
        [query setObject:(id)[NSString stringWithCString:dataType encoding:NSUTF8StringEncoding] forKey:(id)kSecAttrAccount];

        OSStatus err = SecItemDelete((CFDictionaryRef)query);

        if (err == noErr) {
            return 0;
        } else {
            return (int)err;
        }
    }
}

Keychain Services は Security フレームワークを利用するため、KeychainService.mm に対して Security フレームワークの依存関係を設定する必要があります。

KeychainService.mm で Security フレームワークの利用を可能にする

その後、上記を Unity スクリプトから実行可能にするための C# クラスを作成します。本記事ではファイルを Assets/Scripts/KeychainService.cs に配置します。

using System.Runtime.InteropServices;

/// <summary>
///     実装は <c>Assets/Plugins/iOS/KeychainService.mm</c> に記載
/// </summary>
/// <remarks>
///     <a href="https://developer.apple.com/documentation/security/keychain_services">Keychain Services</a>
/// </remarks>
class KeychainService
{
#if UNITY_IOS
    [DllImport("__Internal")]
    private static extern int addItem(string dataType, string value);

    [DllImport("__Internal")]
    private static extern string getItem(string dataType);

    [DllImport("__Internal")]
    private static extern int deleteItem(string dataType);
#endif

    public bool Put(string key, string value)
    {
#if UNITY_IOS
        // 返却されるステータスが 0 なら成功
        return addItem(key, value) == 0;
#endif
    }

    public string Get(string key)
    {
#if UNITY_IOS
        return getItem(key);
#else
        return null;
#endif
    }

    public bool Delete(string key)
    {
#if UNITY_IOS
        // 返却されるステータスが 0 なら成功
        return deleteItem(key) == 0;
#endif
    }
}

あとは用途に応じて下記のようなコードで設定値の保存や取得などを行えます。

// ...
var _keychainService = new KeychainService();

// name をキーとして値を nikaera で保存する
_keychainService.Put("name", "nikaera");

// name をキーとして値を取得する
var name = _keychainService.Get("name");

// "nikaera" が出力される
Debug.Log(name);

//　name をキーとして値を削除する
_keychainService.Delete("name");

// ...

(余談) インターフェースで iOS/Android のふるまいを共通化する

このままだとプラットフォームを切り替える毎にコードを書き直さないとならないので、インターフェースを利用して共通化を行います。

public interface ISecretManager
{
    /// <summary>
    /// 指定したキーで値を保存する関数
    /// </summary>
    /// <param name="key">キー</param>
    /// <param name="value">値</param>
    /// <returns>保存に成功したかどうか</returns>
    bool Put(string key, string value); 

    /// <summary>
    /// 指定したキーの値を取得する関数
    /// </summary>
    /// <param name="key">キー</param>
    /// <returns>指定したキーで設定された値、無ければ null</returns>
    string Get(string key);

    /// <summary>
    /// 指定したキーの値を削除する関数
    /// </summary>
    /// <param name="key">キー</param>
    /// <returns>削除に成功したかどうか</returns>
    bool Delete(string key);
}

その後、Assets/Scripts/EncryptedSharedPreferences.cs および Assets/Scripts/KeychainService.cs を下記の通り ISecretManager の実装に紐付けます。

using UnityEngine;

/// <summary>
///     利用するネイティブコードは <c>Assets/Plugins/Android/SecretManager.java</c> に記載
/// </summary>
/// <remarks>
///     <a href="https://developer.android.com/reference/androidx/security/crypto/EncryptedSharedPreferences">EncryptedSharedPreferences</a>
/// </remarks>
class EncryptedSharedPreferences: ISecretManager
{
    private readonly AndroidJavaObject _secretManager;
    public EncryptedSharedPreferences()
    {
        var activity = new AndroidJavaClass("com.unity3d.player.UnityPlayer")
            .GetStatic<AndroidJavaObject>("currentActivity");
        var context = activity.Call<AndroidJavaObject>("getApplicationContext");
        _secretManager = new AndroidJavaObject("com.nikaera.SecretManager", context);
    }

    #region ISecretManager

    public bool Put(string key, string value)
    {
        return _secretManager.Call<bool>("put", key, value);
    }

    public string Get(string key)
    {
        return _secretManager.Call<string>("get", key);
    }

    public bool Delete(string key)
    {
        return _secretManager.Call<bool>("delete", key);
    }

    #endregion
}

using System.Runtime.InteropServices;

/// <summary>
///     実装は <c>Assets/Plugins/iOS/KeychainService.mm</c> に記載
/// </summary>
/// <remarks>
///     <a href="https://developer.apple.com/documentation/security/keychain_services">Keychain Services</a>
/// </remarks>
class KeychainService: ISecretManager
{
#if UNITY_IOS
    [DllImport("__Internal")]
    private static extern int addItem(string dataType, string value);

    [DllImport("__Internal")]
    private static extern string getItem(string dataType);

    [DllImport("__Internal")]
    private static extern int deleteItem(string dataType);
#endif

    // KeychainService.mm に定義した関数を呼び出す
    #region ISecretManager

    public bool Put(string key, string value)
    {
#if UNITY_IOS
        return addItem(key, value) == 0;
#else
        return false;
#endif
    }

    public string Get(string key)
    {
#if UNITY_IOS
        return getItem(key);
#else
        return null;
#endif
    }

    public bool Delete(string key)
    {
#if UNITY_IOS
        return deleteItem(key) == 0;
#else
        return false;
#endif
    }

    #endregion
}

あとは上記をよしなに利用可能な SecretManager クラスを作成します。

using UnityEngine;

/// <summary>
///     <em>Editor 利用時のみ PlayerPrefs を利用する</em>
/// </summary>
/// <remarks><see cref="KeychainService" />, <see cref="EncryptedSharedPreferences" /></remarks>
public static class SecretManager
{
#if UNITY_EDITOR
#elif UNITY_ANDROID
        private static ISecretManager _instance = new EncryptedSharedPreferences();
#elif UNITY_IOS
        private static ISecretManager _instance = new KeychainService();
#endif

        public static bool Put(string key, string value)
        {
#if UNITY_EDITOR
                PlayerPrefs.SetString(key, value);
                PlayerPrefs.Save();

                return true;
#elif UNITY_IOS || UNITY_ANDROID
                return _instance.Put(key, value);
#else
                Debug.Log("Not Implemented.");
                return false;
#endif

        }

        public static string Get(string key)
        {
#if UNITY_EDITOR
                return PlayerPrefs.GetString(key);
#elif UNITY_IOS || UNITY_ANDROID
        return _instance.Get(key);
#else
            Debug.Log("Not Implemented.");
            return null;
#endif
        }

        public static bool Delete(string key)
        {
#if UNITY_EDITOR
            PlayerPrefs.DeleteKey(key);
            PlayerPrefs.Save();

            return true;
#elif UNITY_IOS || UNITY_ANDROID
            return _instance.Delete(key);
#else
            Debug.Log("Not Implemented.");
            return false;
#endif
        }
}

これでプラットフォーム間の実装差異を気にすることなく、下記のような記述で設定値の保存や取得などを行えます。iOS/Android 以外のプラットフォームで追加実装したい場合はプラットフォーム依存コンパイルと ISecretManager の実装クラスを新たに作成することで簡単に追加できます。

// ...
// name をキーとして値を nikaera で保存する
SecretManager.Put("name", "nikaera");

// name をキーとして値を取得する
var name = SecretManager.Get("name");

// "nikaera" が出力される
Debug.Log(name);

//　name をキーとして値を削除する
SecretManager.Delete("name");

// ...

おわりに

今回は iOS/Android で設定値をセキュアに扱うための方法についてまとめてみました。実際は Keychain Services 周りは実装が大変なので、External Dependency Manager for Unity とか使って KeychainAccess のような外部ライブラリを利用する構成のほうが良いと思われます。

本記事の内容に誤りがあったり、実際にはセキュアな実装ができていない等々あれば是非コメントでご指摘いただけますと幸いです。

参考リンク

逆に External Dependency Manager for Unity を利用する方法のメリットは、UnityPackage などでライブラリとして配布する際に、ライブラリを動作させるのに必要な外部パッケージも同梱した状態で配布が可能になるなどがあります。(当然ライセンスには気を付ける必要がありますが...) ↩
パッケージの依存関係を自動で解決するかどうかという選択肢になります。本記事では明示的に Resolve を実行するため Disable でも Enable でも進行上の問題はありません。 ↩
CocoaPods もサポートされているようなので、iOS でも Android 同様、外部ライブラリを取り込むのは簡単にできそうでした。例えば KeychainAccess とか使いたい。 ↩

[TECH] GameCI で Unity の CI 環境を GitHub Actions で構築する 🎮

nikaera — Wed, 26 May 2021 12:52:59 +0000

はじめに

先日同僚が Unity の CI 環境を構築するためのライブラリである GameCI について教えてくれました。早速 GameCI の GitHub Actions を利用して、サンプルプロジェクトで色々動作検証してみたところ、Unity の CI 環境を楽に構築できることが分かりました。

もちろん、Unity Cloud Build を利用すれば CI 環境の構築は以前から楽にできました。しかし、選択肢の 1 つとして GameCI を持っておくことで、サクッと GitHub Actions に統合する形で Unity の CI 環境を導入できるのは他には無いメリットを感じました。

本記事で紹介しているソースコード、及び検証時に利用したプロジェクトは GitHub にアップ済みですので、手っ取り早く内容を把握されたい方は下記をご参照くださいませ。

https://github.com/nikaera/Unity-GameCI-Sample

業務でも利用できそうなので、GameCI を利用して CI 環境を構築する手順を記事でまとめました。

GameCI に備わっている機能紹介

GameCI には現状下記の GitHub Actions が用意されているようです。

機能	概要
Activation	Unity ライセンスを任意の Unity バージョンで発行する
Test runner	Unity の PlayMode 及び EditMode のテストを実行する (テスト結果の出力にも対応)
Builder	任意の Platform ビルドを実行する (アーティファクト利用でダウンロードも可能)
Returning a license	Unity ライセンスの返却ができる (Professional License のみ対応)
Remote builder	GitHub Actions のスペックでは満足のいくビルドができない際に AWS 環境でハイスペックなマシンを用意してビルドできる。ビルドのためのインフラ構築には AWS CloudFormation を使用している (現在は AWS のみ対応。今後 GCP, Azure にも対応予定とのこと)
Deployment	Unity ビルドを各種 Platform 向けにデプロイする (iOS 及び Android のみ記載あり。厳密に言うと `Builder` でビルド出力した内容を `fastlane` を用いてデプロイするためのワークフロー紹介になっている)

上記を見ると既に GameCI には開発者として Unity CI に欲しい機能は最低限揃っているように見受けられました。 また本記事では、今後機会があれば試してみたいと考えていますが Remote builder 及び Deployment については言及していません。

今回は実例を交えながら Activation 及び Test runner、Builder、Returning a license の使用方法について紹介していきます。

Activation: GameCI で必要となる Unity License のアクティベーションを行う

GameCI で Unity ライセンスをアクティベートするには Activation を利用します。早速ドキュメントの手順に沿って作業を進めていきます。

まず CI を導入したい GitHub 上の Unity プロジェクトの .github/workflows 内に Unity ライセンスアクティベート用のワークフローファイルを作成します。

name: Acquire activation file
on:
  workflow_dispatch: {}
jobs:
  activation:
    name: Request manual activation file 🔑
    runs-on: ubuntu-latest
    steps:
      # GameCI の Activation を利用して alf ファイルを発行する
      - name: Request manual activation file
        id: getManualLicenseFile
        uses: game-ci/unity-request-activation-file@v2
        with:
          # Unity プロジェクトのバージョンを指定する
          # ProjectSettings/ProjectVersion.txt に記載されているバージョンを入力すれば OK
          unityVersion: 2020.3.5f1
      # Upload artifact (Unity_v20XX.X.XXXX.alf)
      - name: Expose as artifact
        uses: actions/upload-artifact@v2
        with:
          name: ${{ steps.getManualLicenseFile.outputs.filePath }}
          path: ${{ steps.getManualLicenseFile.outputs.filePath }}

その後、デフォルトブランチにプッシュして GitHub Actions で実行可能にしたら、下記手順に従い Unity ライセンスファイルのアクティベート及びダウンロードを行います。

1. ブラウザから GitHub リポジトリにアクセスして、Unity ライセンスアクティベート用のワークフローを実行して alf ファイルを生成する

2. ワークフローの実行に成功したら、該当項目をクリックして詳細画面に遷移する

3. Artifacts の項目から alf ファイルをダウンロードする

4. Unity license manual activation webpage からログインして alf ファイルをアップロードする

5. Unity ライセンスの利用用途に応じて適切な選択肢を入力する (本記事では Personal ライセンスを選択)

6. Download license ボタンをクリックして ulf ファイルをダウンロードする

これで Unity ライセンスファイルのアクティベートは完了です。次にアクティベートしたライセンスファイルを GitHub リポジトリの Secrets に登録して、GameCI で PlayMode 及び EditMode のテストが実行できるようにしていきます。

alf 拡張子のファイルがライセンスリクエストファイルを指していて、Unity ライセンスの発行に必要となるファイルです。ulf 拡張子のファイルが Unity ライセンスのファイルです。¹

Test runner: PlayMode 及び EditMode テストを実行して結果を参照する

GitHub Actions 上でテストを実行するために、先ほどアクティベートした Unity ライセンスの情報をワークフロー上で扱えるようにする必要があります。そのため、まずは Secrets に ulf ファイルの内容を登録することから始めます。

1. Unity ライセンスの情報登録のため、Github リポジトリの Secrets 登録画面に遷移する

2. GameCI はライセンス情報参照のため、デフォルト設定では Secrets の UNITY_LICENSE を参照する。そのため、Name が UNITY_LICENSE、Value には ulf ファイルの中身を登録する²

上記作業で GameCI でテストやビルド実行を行える環境が整ったので、動作検証のためテスト実行用のワークフローファイルを作成します。

name: Run EditMode and PlayMode Test
on:
  workflow_dispatch: {}
jobs:
  test:
    name: Run EditMode and PlayMode Test
    runs-on: ubuntu-latest
    steps:
      # actions/checkout@v2 を利用して作業ディレクトリに
      # Unity プロジェクトの中身をダウンロードしてくる
      - name: Check out my unity project.
        uses: actions/checkout@v2

      # GameCI の Test runner を利用して
      # EditMode 及び PlayMode のテストを実行する
      - name: Run EditMode and PlayMode Test
        uses: game-ci/unity-test-runner@v2
        env:
          # 2. の手順で Secrets に登録した Unity ライセンスの情報を指定する
          UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}

          # もし Professional license を使いたい場合は、
          # メールアドレス、パスワード、シリアルナンバーを入力する必要がある
          # ref: https://game.ci/docs/github/test-runner#professional-license
          # UNITY_EMAIL: ${{ secrets.UNITY_EMAIL }}
          # UNITY_PASSWORD: ${{ secrets.UNITY_PASSWORD }}
          # UNITY_SERIAL: ${{ secrets.UNITY_SERIAL }}
        with:
          projectPath: .
          # テストの実行結果もみたい場合は githubToken を指定する
          # secrets.GITHUB_TOKEN は Secrets 未登録でも利用可能
          githubToken: ${{ secrets.GITHUB_TOKEN }}

          # Unity プロジェクトのバージョンを指定する
          # ProjectSettings/ProjectVersion.txt に記載されているバージョンを入力すれば OK
          unityVersion: 2020.3.5f1

          # 実行したいテストの種類を指定できる
          # 指定可能な値は All, PlayMode, EditMode
          # testMode: All

          # テスト実行時に利用したい Docker イメージを明示的に指定できる
          # customImage: 'unityci/editor:2020.1.14f1-base-0'

      # テストの実行結果をアーティファクトにアップロードしてダウンロードして参照できるようにする
      - uses: actions/upload-artifact@v2
        if: always()
        with:
          name: Test results
          path: artifacts

上記のワークフローファイルを GitHub Actions 上で動作検証する際の手順は下記になります。

1. Unity のテストを実行するためのワークフローを選択して実行する

2. ワークフローの実行が成功したら、詳細画面に遷移した後、Test Results の項目からテストの実行結果を確認する

テスト実行用のワークフローファイルでは workflow_dispatch で実行可能にしていますが、pull_request を利用すればプルリク時にテストを実行させることが可能になります。

Builder: プロジェクトのビルドを実行して出力結果を確認する

GameCI にはプロジェクトのビルドを行うための GitHub Actions も用意されています。実際に GameCI で WebGL ビルドを行いその内容を GitHub Pages で確認できるようにして動作検証していきます。

早速 WebGL ビルドを行うためのワークフローファイルを作成していきます。

name: Run the WebGL build
on:
  workflow_dispatch: {}
jobs:
  build:
    name: Run the WebGL build
    runs-on: ubuntu-latest
    steps:
      # actions/checkout@v2 を利用して作業ディレクトリに
      # Unity プロジェクトの中身をダウンロードしてくる
      - name: Check out my unity project.
        uses: actions/checkout@v2

      # GameCI の Builder を利用して、
      # Unity プロジェクトのビルドを実行する
      - name: Run the WebGL build
        uses: game-ci/unity-builder@v2
        env:
          UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}
        with:
          # 今回は WebGL ビルドを行いたいため WebGL を指定する
          # WebGL 以外の指定可能な値は下記に記載の値が利用可能
          # ref: https://docs.unity3d.com/ScriptReference/BuildTarget.html
          targetPlatform: WebGL

          unityVersion: 2020.3.5f1
      # Builder で出力した WebGL ビルドを GitHub Pages にデプロイする
      - name: Deploy to GitHub Pages
        uses: JamesIves/github-pages-deploy-action@4.1.3
        with:
          # GitHub Pages デプロイ用の Orphan ブランチ名を指定する
          branch: gh-pages

          # デプロイ用ビルドフォルダパスを指定する
          # GameCI の Builder はデフォルトでは build フォルダにビルド内容を出力する
          folder: build

      # Builder で出力した WebGL ビルドをアーティファクトでダウンロード可能にする
      - name: Upload the WebGL Build
        uses: actions/upload-artifact@v2
        with:
          name: Build
          path: build

上記のワークフローファイルを GitHub Actions 上で動作検証する際の手順は下記になります。

1. Unity の WebGL ビルドを実行するためのワークフローを実行する

2. ワークフローの実行が成功したら、詳細画面に遷移した後、ビルド内容が正常そうか確認する

3. ビルド内容を確認するための GitHub Pages の設定を Settings から行う

4. GitHub Pages でブラウザから WebGL ビルドの動作確認をする

上記のように Builder を利用することで WebGL ビルドの成否及び、最新のビルド内容を常に GitHub Pages で見られるようにできます。 すると WebGL ビルドが正常かどうかの確認が常に GitHub Pages を見れば把握できるようになるため、Unity1 週間ゲームジャムなどに参加する際で便利に活用できそうです。

WebGL ビルドを行う際、Unity バージョンやアセットの対応状況によっては正しくブラウザ上で動作しないビルドが出力されます。ただし、ブラウザで発生するエラー内容によっては WebGL のビルド設定を見直すだけで解決できる場合があります。 例えば unityframework is not defined というエラーが発生した際は、この記事のように WebGL の Build Settings を見直すことで解決できる場合があります。

私の環境では JamesIves/github-pages-deploy-action で GitHub Pages へのデプロイを行った際、デフォルトでは /WebGL/WebGL フォルダにビルド内容が出力されました。そのため、ブラウザから WebGL ビルドにアクセスする際、<GitHub Pages の URL>/WebGL/WebGL のような URL にアクセスする必要がありました。

Returning a license: GameCI で利用している Unity License を返却する

通常利用することは無いと公式サイトにも書かれていますが、Professional License の返却も GameCI で行うことが可能です。 今回は Personal License を利用したため使用しませんでしたが、下記をワークフローのステップに組み込むことで Professional License を返却できるようです。

# ...
# どこかのタイミングでライセンスのアクティベートを行う
- name: Activate Unity
  uses: game-ci/unity-activate@v1
  env:
    UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}

#...
# ステップの最後などに game-ci/unity-return-license@v1 を呼び出して
# アクティベート済みのライセンスを返却する
- name: Return license
  uses: game-ci/unity-return-license@v1
  if: always()

おわりに

以前 Unity コマンドを駆使して自分で CI 環境を構築した経験があるのですが、
GameCI を利用した方が全然楽に Unity CI 環境構築を GitHub Actions 上で行えました。

ちなみに GameCI で利用されている Docker イメージは以前からよく使われていた gableroux/unity3d が元になっているようでした。ってか GabLeRoux さんのホームページを見たら、GameCI の開発を始めた方のようでした。すごい。

本記事が GitHub Actions で Unity CI 環境構築を始めようとしている方の助けになれれば幸いです。

参考リンク

alf ファイル及び ulf ファイルの実態は XML ファイルです。 ↩
適当なテキストエディタで ulf ファイルを開き全文をコピー & ペーストします。 ↩

[TECH] Zenn の記事を DEV に自動的に同期させる GitHub Actions 作ってみた 📌

nikaera — Mon, 22 Mar 2021 03:12:11 +0000

はじめに

去年 DEV のアカウントを作成したものの、今まで全く有効活用出来ていませんでした。

DEV にはカノニカル URL を設定出来るので、常々 Zenn の記事を投稿する際にクロスポストしたいなと考えておりました。そこで、Zenn に記事を投稿したら、自動的に DEV にも記事を投稿 & 同期する GitHub Actions を作ってみました。

https://github.com/nikaera/sync-zenn-with-dev-action

今回初めて GitHub Actions を自作したのですが、その中で得た知見を残す形で記事を書くことにしました。また、GitHub Actions は TypeScript で作成しました。

開発した GitHub Actions の概要

まずはザッとどのような GitHub Actions を作成したのか、概要について説明いたします。

GitHub リポジトリで管理している Zenn の記事を DEV に同期して投稿する GitHub Actions を作成しました。 その際に DEV へ投稿する記事には Zenn の該当記事へのカノニカル URL も自動で設定できます。これにより DEV と Zenn へ記事をシームレスにクロスポストすることが可能となります。

今回作成した GitHub Actions を利用するワークフローファイルの一例は下記となります。

name: "Sync all Zenn articles to DEV"
on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: checkout my project
        uses: actions/checkout@v2
      - name: dev.to action step
        uses: nikaera/sync-zenn-with-dev-action@v1
        # id を設定することで、後のジョブで Output で指定した値が参照可能になる
        id: dev-to
        with:
          # DEV の API キーを指定する
          api_key: ${{ secrets.api_key }}
          # (オプション) DEV に記事を投稿した際に Zenn のカノニカル URL を設定したい場合に指定する
          # username: nikaera
          # (オプション) 改行区切りで指定した articles フォルダ内のファイルパスを記載した txt ファイルを指定することで、記載された記事のみを同期するようになる。
          # 他プラグインと組み合わせることで差分のみを txt ファイルに載せることが可能。詳細については後述の Outputs の項目に記載。
          # added_modified_filepath: ./added_modified.txt
          # (オプション) Zenn の articles 以下全ての記事を常に DEV に同期するか指定する
          # update_all が true のときは added_modified_filepath は無視される。
          # update_all: false
        # 上記アクション実行時に DEV に新規で同期する記事に関しては Zenn のマークダウンヘッダに
        # 該当する DEV の記事の ID が dev_article_id として記載されるようになる。
        # 今後はその ID を元に同期するようになるため、該当する Zenn の記事をコミットする。
        # 新規で同期する記事が無ければ、このジョブは実行しない。
      - name: write article id of DEV to articles of Zenn.
        run: |
          git config user.name github-actions
          git config user.email github-actions@github.com
          git add ${{ steps.dev-to.outputs.newly-sync-articles }}
          git commit -m "sync: Zenn with DEV [skip ci]"
          git push
        if: steps.dev-to.outputs.newly-sync-articles
        # Outputs には DEV の記事情報 (title, url) が含まれるようになるため、
        # 最後に出力して実行結果の内容を確認することもできる
      - name: Get the output articles.
        # dev-to という id が紐付いたジョブの Outputs を取得して echo で内容を出力する
        run: echo "${{ steps.dev-to.outputs.articles }}"

簡単に nikaera/sync-zenn-with-dev-action@v1 というジョブの内部処理について説明いたします。

Inputs の update_all 及び added_modified_filepath で受け取った情報を元に、どの記事を DEV に同期させるか判定する
DEV に同期する記事のファイルパス一覧を取得して、それぞれの記事のヘッダに dev_article_id の記載があるか判定する
Inputs の api_key を利用して、Zenn の記事に dev_article_id が含まれていれば、該当する DEV の記事を更新する。含まれていなければ DEV に新規で記事を作成する
Inputs の username を利用して、 DEV の記事に該当する Zenn 記事のカノニカル URL を設定する
DEV に新規で記事を作成した場合は、 Zenn の該当記事のヘッダに dev_article_id を書き込む
DEV に記事を投稿する際、Zenn は対応しているが、 DEV では対応していない記述は削除する (`
記事の公開ステータス及びタグなどについても DEV の記事に反映する¹
新規で DEV に記事を同期した Zenn 記事のファイルパスを、 Outputs の newly-sync-articles に設定する (後のジョブで dev_article_id の含まれた記事をコミットしたいため)
ワークフローで同期された記事情報は Outouts の articles に設定する

Inputs と Outputs の内容一覧については下記になります。

Inputs

キー	説明	必須
api_key	DEV の API Key を設定する	o
username	Zenn の自分のアカウント名を設定する (DEV に同期する記事に Zenn のカノニカル URL を設定したい場合のみ)	x
added_modified_filepath	改行区切りで指定した articles フォルダ内のファイルパスを記載した txt ファイルを指定することで、記載された記事のみを同期するようになる。PR やコミット差分のファイルのみを取得するための GitHub Actions jitterbit/get-changed-files@v1 と組み合わせることで、更新差分のあった記事のみを随時同期することも可能。² 更新差分のあった記事のみを随時同期するための実際のワークフローファイルはこちら	x
update_all	Zenn の全ての記事をどうきするかどうかを設定する。GitHub Actions 初回実行時のみ true にする使い方を想定している。デフォルトは true。`added_modified_filepath` よりも `update_all` が優先されるため `added_modified_filepath` を設定する場合は false を設定する必要あり`	x

Outputs

キー	説明
articles	同期された DEV の記事のタイトル及び URL が格納された配列
newly-sync-articles	DEV で新たに新規作成された Zenn 記事のファイルパスが格納された配列。実際のワークフローファイルの該当する記述のように、必ずコミットに含めるようにする必要がある (理由は後述)

Inputs 及び Outputs については公式サイトの説明をご参照ください。

Zenn の記事を DEV に同期するための仕組み

Zenn の記事を新規で DEV に同期する際は、DEV に記事を新規作成する必要があります。その際に Zenn の記事と DEV の記事を紐付けるための何らかの仕組みが必要となります。そうしないと、今後 Zenn の記事内容を更新した際に、DEV のどの記事に内容を同期させればよいかが不明なためです。

そこで、記事を同期するための仕組みとして、dev_article_id というフィールドを Zenn のマークダウンヘッダに追記することで DEV の同期すべき記事との紐付けを行うことにしました。dev_article_id には DEV の記事作成 API 実行時の返り値である id を設定します。

一度 id を dev_article_id として Zenn の記事に紐付けてしまえば、次回以降に記事の同期を行う際は DEV の記事更新 API を利用できます。

また、Outputs の newly-sync-articles には新規で作成された DEV 記事の id である dev_article_id が追記された Zenn 記事のファイルパスが格納されています。そのため、nikaera/sync-zenn-with-dev-action@v1 実行後は、下記のように steps.dev-to.outputs.newly-sync-articles 内に格納されたファイル群をコミットに反映させる必要があります。

# `nikaera/sync-zenn-with-dev-action@v1` 実行後に必ず定義すべきジョブ
# DEV に新規に作成した記事がなければ実行しない (if: steps.dev-to.outputs.newly-sync-articles)
- name: write article id of DEV to articles of Zenn.
    run: |
        git config user.name github-actions
        git config user.email github-actions@github.com
        git add ${{ steps.dev-to.outputs.newly-sync-articles }}
        git commit -m "sync: Zenn with DEV [skip ci]"
        git push
    if: steps.dev-to.outputs.newly-sync-articles

上記のジョブで newly-sync-articles に格納された dev_article_id が追記された Zenn 記事は随時コミットに反映しないと、Zenn の全ての記事が同期毎 DEV に新規作成され続けるという不具合を引き起こしてしまうので、ご注意ください

GitHub Actions を開発する手順

サクッと開発に取り組みたかったため、Docker コンテナを利用する方法ではなく、JavaScript を利用する方法で開発を進めていくことにしました。

TypeScript で GitHub Actions を作る

GitHub 公式が TypeScript で GitHub Actions を作るためのテンプレートプロジェクトを用意してくれています。今回はこのテンプレートプロジェクトを利用する形でプロジェクトを作成しました。

(余談) GitHub Actions では Docker コンテナを用いてワークフローを実行可能です。そのため、実行環境は自由に設定出来ます。(Go, Python, Ruby, etc.)

早速 TypeScript のテンプレートプロジェクトを元に自分の GitHub Actions プロジェクトを作成します。

1. テンプレートプロジェクトを元に GitHub Actions の TypeScript プロジェクトを作成する

2. プロジェクトの作成後 git clone してきて開発する準備を整える

GitHub Actions プロジェクトの開発を進めるための準備を行う

テンプレートプロジェクトを git clone したら、まずは action.yml の内容を変更します。
今回作成した GitHub Actions の action.yml は下記となっております。

# GitHub Actions のプロジェクト名
name: 'Sync Zenn articles to DEV'
# GitHub Actions のプロジェクト説明文
description: 'Just sync Zenn articles to DEV.'
# GitHub Actions の作者
author: 'nikaera'
# GitHub Actions に渡せる引数の値定義
inputs:
  api_key:
    # フィールドの指定が必須であれば true、必須でなければ false を設定する
    # DEV の API キーは同期を行う際に必須なため、true を設定している
    required: true
    # フィールドの説明文
    description: 'The api_key required to use the DEV API (https://docs.forem.com/api/#section/Authentication)'
  username:
    required: false
    description: "Zenn user's account name. (Fields to be filled in if canonical url is set.)"
  articles:
    required: false
    description: "The directory where Zenn articles are stored."
    # フィールドにはデフォルト値を指定することも可能
    # Zenn の記事がデフォで格納されているフォルダ名を指定している
    default: articles
  update_all:
    require: false
    description: "Whether to synchronize all articles."
    default: true
  added_modified_filepath:
    required: false
    description: |
      Synchronize only the articles in the file path divided by line breaks.
      You can use jitterbit/get-changed-files@v1 to get only the file paths of articles that have changed in the correct format.
      (https://github.com/jitterbit/get-changed-files)
# GitHub Actions 実行後に参照可能になる値定義
outputs:
  articles:
    description: 'A list of URLs of dev.to articles that have been created or updated'
  newly-sync-articles:
    description: 'File path list of newly synchronized articles.'
# GitHub Actions の実行環境
runs:
  using: 'node12'
  # テンプレートプロジェクトでは コンパイル先が dist になるため `dist/index.js` を指定している
  main: 'dist/index.js'

TypeScript のテンプレートプロジェクトでは、バンドルツールとして ncc が採用されています。GitHub Actions 実行時に使用されるのは ncc によりコンパイルされた単一の JavaScript ファイル (dist/index.js) になります。

あとは src フォルダ内でプログラムを書いて、npm run all && node dist/index.js のようにコマンド実行しながら開発を進めていくだけです。

(余談) GitHub Actions の開発ツールとして Docker を利用した act というものが存在するようです。ローカル環境で検証する際は既知の問題に対応する必要がありそうですが、GitHub Actions の開発で非常に有効活用できそうで気になっております。

今回の開発では利用しなかったのですが、今後開発を進めていく中で利用する機会も出てきそうなので、その際は本記事内容を更新する形で知見を追記したいと考えております。

GitHub Actions を実装する際に利用した機能

GitHub Actions を実装する際に利用した機能を、実際のコード内容を抜粋して簡単に説明していきます。下記で紹介する内容は GitHub Actions Toolkit の機能です。

/**
下記の yml の with で指定した値は core.getInput で受け取ることが可能。

- name: dev.to action step
    uses: nikaera/sync-zenn-with-dev-action@v1
    id: dev-to
    with:
        # DEV の API キーを指定する
        api_key: ${{ secrets.api_key }}
*/
core.getInput("api_key", { required: true });
core.getInput("update_all", { required: false });

/**
下記の yml の steps.<ジョブで指定した id>.outputs で参照可能な値をセットすることが可能。
セットする内容は文字列である必要がある。

- name: dev.to action step
    uses: nikaera/sync-zenn-with-dev-action@v1
    id: dev-to
- name: Get the output articles.
    run: echo "${{ steps.dev-to.outputs.articles }}"
*/

core.setOutput("articles", JSON.stringify(devtoArticles, undefined, 2));
core.setOutput("newly-sync-articles", newlySyncedArticles.join(" "));

/**
GitHub Actions 実行時に出力されるログをレベルごとに出力することが可能
core.debug はローカル実行時のみに出力内容を確認することができる
*/
core.debug("debug");
core.info(`update_all: ${updateAll}`);
core.error(JSON.stringify(error));

上記だけ把握してれば GitHub Actions の開発は問題なく行うことができました。

作成した GitHub Actions を実際に GitHub 上で実行可能にする

ローカル環境で一通り開発が完了したら、GitHub リポジトリに push した後タグ付けを行います。GitHub Actions はタグを設定しないと実行できないため必要な作業となります。 今回タグ付けは GitHub 上で行いました。

1. タグの項目をクリックする

2. Create a new release ボタンをクリックしてタグ作成画面に遷移する

3. Publish release ボタンをクリックしてタグの作成を完了する

上記の例では v1 というタグを作成したので nikaera/sync-zenn-with-dev-action@v1 のような記述で GitHub Actions を利用可能になりました。 私は Zenn の記事を zenn.dev というリポジトリで管理しているため、早速このリポジトリに GitHub Actions を導入してみます。

Zenn の全ての記事を DEV に同期するためのワークフロー

本記事の GitHub Actions では DEV の API キーを使用するため、事前にシークレットへ API_KEY という名称で値を登録しておきます。公式サイトの手順に従いシークレットの登録が完了したら、該当リポジトリに .github/workflows/sync-zenn-with-dev-all.yml というワークフローファイルを作成します。

name: "Sync-All Zenn with DEV"
on:
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    if: contains(github.event.head_commit.message, '[skip ci]') == false
    steps:
      - name: setup node project
        uses: actions/checkout@v2
      - name: dev.to action step
        uses: nikaera/sync-zenn-with-dev-action@v1
        id: dev-to
        with:
          api_key: ${{ secrets.api_key }}
          # Zenn の自分のアカウント名を指定すると
          # DEV 記事のカノニカル URL に Zenn 記事の URL を指定できる
          # username: nikaera
          update_all: true
      - name: write article id of DEV to articles of Zenn.
        run: |
          git config user.name github-actions
          git config user.email github-actions@github.com
          git add ${{ steps.dev-to.outputs.newly-sync-articles }}
          git commit -m "sync: Zenn with DEV [skip ci]"
          git push
        if: steps.dev-to.outputs.newly-sync-articles
      - name: Get the output articles.
        run: echo "${{ steps.dev-to.outputs.articles }}"

上記は手動実行が可能な Zenn の記事を全て DEV に同期するためのワークフローファイルになります。作成が完了したらワークフローファイルを実行して、記事が正常に同期できているか確認してみます。

1. Actions タブをクリックする

2. 作成した Sync-All Zenn with DEV ワークフローファイルを選択する

3. Run workflow ボタンを実行して、ワークフローを実行する

4. ワークフローの実行が正常に完了していれば、ログに DEV の記事情報が出力される

5. dev.to にアクセスして Zenn の記事情報が正常に同期されていることを確認する

正常に Zenn の全ての記事が DEV に同期されていることが確認できたら、次は Zenn の記事が新規作成されたり、更新されたときのみに DEV に同期するためのワークフローファイルを作成します。

更新差分のあった Zenn 記事のみを DEV に同期するためのワークフロー

main ブランチが更新されたときのみ更新された記事のみを DEV に同期するためのワークフローファイルを作成します。該当リポジトリに .github/workflows/sync-zenn-with-dev.yml というワークフローファイルを作成します。

name: "Sync Zenn with DEV"
on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest
    if: contains(github.event.head_commit.message, '[skip ci]') == false
    steps:
      - name: setup node project
        uses: actions/checkout@v2
      - name: get modified files
        id: files
        uses: jitterbit/get-changed-files@v1
      - name: output modified files to text
        run: |
          for changed_file in ${{ steps.files.outputs.added_modified }}; do
            echo "${changed_file}" >> added_modified.txt
          done
      - name: dev.to action step
        uses: nikaera/sync-zenn-with-dev-action@v1
        id: dev-to
        with:
          api_key: ${{ secrets.api_key }}
          # Zenn の自分のアカウント名を指定すると
          # DEV 記事のカノニカル URL に Zenn 記事の URL を指定できる
          # username: nikaera
          added_modified_filepath: ./added_modified.txt
          update_all: false
      - name: write article id of DEV to articles of Zenn.
        run: |
          git config user.name github-actions
          git config user.email github-actions@github.com
          git add ${{ steps.dev-to.outputs.newly-sync-articles }}
          git commit -m "sync: Zenn with DEV [skip ci]"
          git push
        if: steps.dev-to.outputs.newly-sync-articles
      - name: Get the output articles.
        run: echo "${{ steps.dev-to.outputs.articles }}"

上記ワークフローファイルの作成が完了したら、早速動作確認のために、まさに今執筆中の本記事内容をリポジトリに push してみます。

1. git push 後に該当するワークフローの実行結果を確認する

2. dev.to に執筆途中の内容で記事が同期されていることを確認する

これまで説明してきた 2 つのワークフローを利用することで、大抵のユースケースはカバーできるはずです。

おわりに

GitHub Actions の勉強のために取り組んだプロジェクトですが、思いの外楽しくて他にも色々な機能のアイデアがあるので随時実装していきたいと考えています。(英訳, タイトルフォーマット変更, etc.)

DEV に Zenn の記事をクロスポストする GitHub Actions を公開することで、いつもお世話になっている Zenn というプラットフォームを海外の方に認知していただける機会を創出できたのかもと考えたらテンションが上がってきました。

それはさておき、Zenn の記事を他でも有効活用するための GitHub Actions を開発する際には、恐らく本記事で紹介した GitHub Actions のコードが参考になるはずです。

また、GitHub Actions の Marketplace というものが用意されているようなので、開発がある程度完了次第、こちらに申請するのも試してみたいと考えております。

参考リンク

DEV (Forem) の仕様上、タグは最大でも 4 つまでしか設定できないため、Zenn で設定したタグの先頭 4 つまで DEV の記事には設定しています ↩
当然といえば当然ですが jitterbit/get-changed-files@v1 は workflow_dispatch でワークフローを手動実行した際や、force push 等でファイル差分を正確に特定できない操作には対応しておりませんので、その場合はエラーが発生します ↩

[TECH] AWS Lightsail Containers に Actix web をデプロイする ⛵

nikaera — Sat, 20 Mar 2021 18:54:43 +0000

はじめに

Actix web で Web アプリケーションを作ったのですが、技術勉強も兼ねていたので、デプロイ先も今まで試したことがないものを試そうとしていました。そこで、日頃業務でも AWS を利用しているということもあり、去年末に発表された AWS Lightsail Containers をデプロイ先に採用しました。

AWS Lightsail Containers へのデプロイ自体は非常に簡単でした。また、デプロイにあたり Rust の Docker イメージ作成のやり方も学べました。今回はそのあたりの手順をまとめる形で記事として書き残しておくことにしました。

Actix web の Docker イメージを作成する

開発したアプリケーションでは React でフロントエンド開発をしていて、ビルドしたものを Actix web の public フォルダに配置する形で公開しています。そのため、下記の Dockerfile ではマルチステージビルドを利用しておりますが、本質的には FROM rust:1.49 以降の記述が Actix web に関するものとなります。

# React ビルド用のイメージ
FROM node:14.15.4-alpine3.10 as client_builder

ARG REACT_APP_API_URL
ARG REACT_APP_GYAZO_AUTH_URL
ARG REACT_APP_GA_UNIVERSAL_ID

WORKDIR /client
COPY ./client/package*.json .
RUN yarn install

ADD ./client .
RUN yarn build

# Actix web ビルド用のイメージ
FROM rust:1.49

# Actix web にアクセスするためのポートを公開する
EXPOSE 8080

# Actix web プロジェクトのフォルダをイメージに追加する
WORKDIR /server
ADD ./server .

# プロジェクトフォルダ内で `cargo install` してビルドを生成する
RUN cargo install --path .

# 不要になったファイル群を削除する
RUN ls | grep -v -E 'templates' | xargs rm -r

# React ビルド用のイメージでビルドした内容を Actix web ビルド用イメージに追加する
COPY --from=client_builder /client/build ./build
RUN mkdir tmp

# `cargo install` コマンドで生成したビルドを実行して Actix web を起動する
# 下記のコマンド名称は Cargo.toml 内の [package.name] に準ずる
CMD ["bloggimg-server"]

また、Docker ビルド時のオプション管理を楽にするため、Docker Compose を利用しました。単一の Docker イメージをビルドする際にも利用しておくことで、後々コンテナを追加して連携させたいときにも即座に対応できたりでオススメです。

# context に Actix web プロジェクトのパスを指定する
# args に Docker ビルド時に利用したい ARGS の値を環境変数で設定する
# image に Docker の <イメージ名:タグ名> を指定する (今回は Docker Hub にデプロイする想定)
# env_file に開発/動作検証時に利用したい dotenv ファイルを指定する
# ports にポートマッピングの設定を書く

version: '3.8'
services:
  app:
    build:
      context: ./
      args:
        - REACT_APP_API_URL=${REACT_APP_API_URL}
        - REACT_APP_GYAZO_AUTH_URL=${REACT_APP_GYAZO_AUTH_URL}
        - REACT_APP_GA_UNIVERSAL_ID=${REACT_APP_GA_UNIVERSAL_ID}
    image: n1kaera/bloggimg:v1.0.0
    env_file:
      - ./server/.env
    ports:
      - 8080:8080

上記を自分の Actix web プロジェクトに応じて改変し docker-compose up して動作検証します。動作検証ができ次第、docker-compose build を実行して Docker イメージをビルドします。ビルドに成功したら次は Docker Hub にイメージを push します。

Docker Hub にビルドしたイメージを push する

今回は AWS Lightsail Containers で使用するイメージの管理に Docker Hub を利用します。Docker Hub へ push する前に docker login --username=<Docker Hub のユーザ名> コマンドで Docker Hub へのログインを済ませておきます。

その後 docker-compose push コマンドで Docker イメージを Docker Hub に push します。

Docker Hub のページから、正常に Docker イメージが push できていそうか確認する

Docker イメージの push が成功していることを確認できたら、残りは AWS Console 上での作業になります。

AWS Console から Lightsail Containers Service を作成する

AWS Console にログイン後、Lightsail サービスを選択して Lightsail サービスのトップページへ遷移します。遷移したら Containers タブを選択し、Create container services ボタンから Container Service を作成します。

AWS Console へログイン後 Lightsail のページに遷移して、Containers タブを選択する

Containers タブを選択すると出てくる、Create container services ボタンをクリックする

Create container services ボタンをクリックした遷移先の画面で、リージョンやキャパシティ (Micro であれば 3 ヶ月間のみ無料で利用可能) 等を選択して、名称を入力します。今回は最初にデプロイのための準備をすでに済ませているので、Container Service を作成するついでにデプロイ設定も行います。

デプロイ設定は Set up your first deployment の項目から行うことが可能です。

Set up deployment の部分をクリックして、デプロイの設定項目を表示する

Docker Hub イメージを利用してデプロイする際に必要な設定項目を入力する

コンテナのヘルスチェックのための情報を入力する

すべての情報入力が完了したら Create container services ボタンをクリックする

遷移後の画面下部の Deployment versions からデプロイ状況の確認が行える

正常にデプロイできていれば Deployment versions の項目が Active になる

デプロイが完了したら Public domain が発行されているはずなので、正常にアクセスして Web アプリケーションが利用できそうか確認します。Public domain は該当する Container Service のトップページから確認できます。

AWS Lightsail Containers のトップページにある Public domain から動作検証する

一通りの動作検証を行い、正常にデプロイできていそうか確認する

これで作業は完了です。新しい Docker イメージでデプロイし直したい場合は、Deployments タブの Modify your deployment リンクをクリックすれば可能です。

(おまけ) 独自ドメインで Container Service へアクセス可能にする

AWS Lightsail Containers では独自ドメインの紐付け及び、HTTPS 化も簡単に設定できます。Custom domains タブを選択した後、画面下部にある Create certificate リンクをクリックすることで設定画面を表示します。

Custom domain タブをクリックしてから、Create certificate リンクをクリックする

各種設定項目の入力が完了したら Create ボタンをクリックする

ドメイン検証のために、CNAME レコードの設定を求められるので各自で設定作業を行う

正常に CNAME レコードを設定した後、しばらく経つと Status が Valid になる

上記まで確認したら、Create certificate で設定したドメインの CNAME レコードに Public domain の値を設定しておきます。設定内容が反映され次第、独自ドメインへアクセスすることで HTTPS 経由で Container Service へアクセスできるようになります。

Custom domains で Container Service で起動しているサービスにアクセスできることを確認する

おわりに

AWS Lightsail Containers を利用して Actix web プロジェクトをデプロイする手順について簡単にまとめてみました。便利ではあるものの、個人開発で利用する分には価格面及び性能面で Lightsail Instance のほうが良いなと現時点では感じてしまいました。

しかし、日本リージョンが用意されていたりロードバランサーを備えていたり、簡単にスケールさせやすくかつ定額で利用可能なサービスであるというメリットを活かせる場面があれば有効活用できそうだなと感じました。

参考リンク

[TECH] MediaPackage 用の CloudFront ディストリビューションを AWS SDK で作成する 🎥

nikaera — Sat, 20 Mar 2021 18:54:35 +0000

はじめに

とある事情で MediaPackage のエンドポイント用の CloudFront ディストリビューションを AWS SDK で作成する機会がありました。その際得た知見をソースコードを交えながら備忘録として記事に残しておきます。

本記事内容で紹介しているソースコードは Gist にも同じ内容でアップしてあります。

ちなみに MediaLive + MediaPackage + CloudFront の構成でインフラ構築したい場合は、CloudFormation が MediaPackage にも対応したので CloudFormation の利用を推奨します。

本記事内容はあくまでも何らかの事情で、後から CloudFront ディストリビューションを MediaPackage エンドポイントに紐づけたいケース等で参考になると思われます。

実装内容

作成したソースコードの内容は下記になります。
最下部の createDistributionForMediaPackage が本記事タイトルに該当する関数です。

import { CloudFront } from "aws-sdk";
import * as url from "url";

import {
    CreateDistributionWithTagsResult,
    GetDistributionResult,
    UpdateDistributionResult
} from "aws-sdk/clients/cloudfront";

export class CloudFrontClientForMediaPackage {
    private cloudFront: CloudFront;

  constructor() {
    this.cloudFront = new CloudFront({
        region: "ap-northeast-1",
        apiVersion: '2020-05-31',
    });
}

/**
 * CloudFront ディストリビューションの情報を取得するために利用する
 * @param id CloudFront ディストリビューションの ID
 * @return ディストリビューションの情報を取得する
 */
  async getDistribution(id: string): Promise<GetDistributionResult> {
      const distribution = await this.cloudFront.getDistribution({
          Id: id
      }).promise()

      return distribution;
  }

  /**
   * CloudFront ディストリビューションの設定内容を取得するために利用する
   * @param id CloudFront ディストリビューションの ID
   * @return ディストリビューションの設定内容を取得する
   */
  async getDistributionConfig(id: string): Promise<CloudFront.DistributionConfig> {
      const config = await this.cloudFront.getDistributionConfig({
          Id: id
      }).promise()

      return config.DistributionConfig;
  }

  /**
   * CloudFront ディストリビューションを削除する
   * @param id 削除したい CloudFront ディストリビューションの ID
   */
  async deleteDistribution(id: string) {
    const distribution = await this.getDistribution(id);

    await this.cloudFront.deleteDistribution({
        Id: id, IfMatch: distribution.ETag
    }).promise()
  }

  /**
   * CloudFront ディストリビューションを無効化する
   * @param id 無効化したい CloudFront ディストリビューションの ID
   * @return 無効化した CloudFront ディストリビューションの情報
   */
  async disableDistribution(id: string): Promise<UpdateDistributionResult> {
      const distribution = await this.getDistribution(id);
      const config = distribution.Distribution.DistributionConfig;
      config.Enabled = false;

      return await this.cloudFront.updateDistribution({
        Id: id,
        IfMatch: distribution.ETag,
        DistributionConfig: config
      }).promise();
  }

  /**
   * MediaPackage のエンドポイント用の CloudFront ディストリビューションを作成する
   * @param id CloudFront ディストリビューションを判別するための ID
   * @param mediaPackageArn MediaPackage チャンネルの ARN
   * @param mediaPackageUrl MediaPackage エンドポイントの URL
   */
  async createDistributionForMediaPackage(
      id: string,
      mediaPackageArn: string,
      mediaPackageUrl: string
    ): Promise<CreateDistributionWithTagsResult> {

    // 1. url モジュールを用いて URL 文字列をパースする
    const mediaPackageEndpoint = url.parse(mediaPackageUrl);

    /**
    2. MediaPackage のエンドポイント URL から FQDN を取得する。
    後述する CloudFront ディストリビューションのオリジンのドメイン名としても利用する
    */
    const mediaPackageHostname = mediaPackageEndpoint.hostname;

    /**
    3. MediaPackage のエンドポイント URL のフォーマットは
    https://<AccountID>.mediapackage.<Region>.amazonaws.com/**** となっているので、
    FQDN の先頭部分を文字列分割で取り出すとアカウント ID が取得できる
    */
    const accountId = mediaPackageHostname.split('.')[0];

    // 4. 後述する CloudFront ディストリビューションのオリジン ID として、アカウント ID を利用する
    const targetOriginId = `MP-${accountId}`

    /**
    5. createDistribution ではなく、createDistributionWithTags 関数で、
    CloudFront ディストリビューションを作成する。MediaPackage との紐付けにタグを利用するため。
    */
    return await this.cloudFront.createDistributionWithTags({
        DistributionConfigWithTags: {
            Tags: {
                Items: [
                    /**
                    !!!!!重要!!!!!

                    6. CloudFront ディストリビューションに紐付けたい
                    MediaPackage エンドポイントのチャンネル ARN を
                    mediapackage:cloudfront_assoc で定義する。

                    mediapackage:cloudfront_assoc を定義することで、
                    CloudFront ディストリビューションと
                    MediaPackage チャンネルを紐付けることが可能となる。
                    */
                    {
                        Key: 'mediapackage:cloudfront_assoc',
                        Value: mediaPackageArn
                    },
                    {
                        Key: 'Id',
                        Value: id
                    },
                    {
                        Key: 'Product',
                        Value: 'product'
                    },
                    {
                        Key: 'Stage',
                        Value: 'dev'
                    }
                ]
            },
            DistributionConfig: {
                CallerReference: new Date().toISOString(),
                Comment: `Managed by MediaPackage - ${id}`,
                Enabled: true,
                /**
                7. CloudFront ディストリビューションのオリジンには 2つ設定します。
                1つが MediaPackage のエンドポイントに対するものと、
                もう 1つが MediaPacakge サービスに対するものです。

                基本的には MediaPackage のエンドポイントに対するオリジンを利用します。
                例外時に向けるオリジンが MediaPacakge サービスに対するものになります。
                */
                Origins: {
                    Quantity: 2,
                    Items: [
                        {
                            DomainName: mediaPackageHostname,
                            Id: targetOriginId,
                            CustomOriginConfig: {
                                HTTPPort: 80,
                                HTTPSPort: 443,
                                OriginProtocolPolicy: 'match-viewer'
                            }
                        },
                        {
                            DomainName: 'mediapackage.amazonaws.com',
                            Id: "TEMP_ORIGIN_ID/channel",
                            CustomOriginConfig: {
                                HTTPPort: 80,
                                HTTPSPort: 443,
                                OriginProtocolPolicy: 'match-viewer'
                            }
                        }
                    ]
                },
                /**
                8. CacheBehaviors のいずれにも当てはまらなかった場合の
                キャッシュの振る舞いを定義します。

                MediaPackage は タイムシフト表示機能を使用する際等で、クエリ文字列に start, m, end を利用しています。
                そのため、それらの文字列は WhitelistedNames に含め QueryString には true を指定しておきます。

                DefaultCacheBehavior に引っかかる挙動は例外的扱いなので、
                使用するオリジンは MediaPackage サービスのものを設定します。
                */
                DefaultCacheBehavior: {
                    ForwardedValues: {
                        Cookies: {
                            Forward: 'whitelist',
                            WhitelistedNames: {
                                Quantity: 3,
                                Items: [
                                    'end', 'm', 'start'
                                ]
                            }
                        },
                        QueryString: true,
                        Headers: {
                            Quantity: 0
                        },
                        QueryStringCacheKeys: {
                            Quantity: 0
                        }
                    },
                    MinTTL: 6,
                    TargetOriginId: "TEMP_ORIGIN_ID/channel",
                    TrustedSigners: {
                        Enabled: false,
                        Quantity: 0
                    },
                    ViewerProtocolPolicy: 'redirect-to-https',
                    AllowedMethods: {
                        Items: [
                            'GET', 'HEAD'
                        ],
                        Quantity: 2,
                    },
                    MaxTTL: 60
                },
                /**
                9. CloudFront のエラーコード全ての TTL に 1sec を設定します。
                MediaPackage のエラーのキャッシュが長時間持続してしまうと、
                その間は MediaPackage で正常に配信できているとしても、
                復旧できない状態となるからです。
                */
                CustomErrorResponses: {
                    Quantity: 10,
                    Items: [
                    {
                        ErrorCode: 400,
                        ErrorCachingMinTTL: 1
                    }, {
                        ErrorCode: 403,
                        ErrorCachingMinTTL: 1
                    }, {
                        ErrorCode: 404,
                        ErrorCachingMinTTL: 1
                    }, {
                        ErrorCode: 405,
                        ErrorCachingMinTTL: 1
                    }, {
                        ErrorCode: 414,
                        ErrorCachingMinTTL: 1
                    }, {
                        ErrorCode: 416,
                        ErrorCachingMinTTL: 1
                    }, {
                        ErrorCode: 500,
                        ErrorCachingMinTTL: 1
                    }, {
                        ErrorCode: 501,
                        ErrorCachingMinTTL: 1
                    }, {
                        ErrorCode: 502,
                        ErrorCachingMinTTL: 1
                    }, {
                        ErrorCode: 503,
                        ErrorCachingMinTTL: 1
                    }
                    ]
                },
                /**
                10. CloudFront ディストリビューションのキャッシュの振る舞いを 2つ定義します。

                それぞれの設定内容は基本的に DefaultCacheBehavior で定義したものと同様です。
                しかし、利用するオリジンは MediaPackage エンドポイントに向けたものを利用します。

                1つは Microsoft Smooth Streaming での配信時に利用する
                index.ism に対するもので Smooth Streaming を true に設定しています。

                もう 1つは上記 Microsoft Smooth Streaming 以外の
                全てに当てはまるストリーミングに適用されるものになります。
                */
                CacheBehaviors: {
                    Quantity: 2,
                    Items: [{
                        MinTTL: 6,
                        PathPattern: 'index.ism/*',
                        TargetOriginId: targetOriginId,
                        ViewerProtocolPolicy: 'redirect-to-https',
                        AllowedMethods: {
                            Items: [
                                'GET', 'HEAD'
                            ],
                            Quantity: 2,
                        },
                        ForwardedValues: {
                            Cookies: {
                                Forward: 'whitelist',
                                WhitelistedNames: {
                                    Quantity: 3,
                                    Items: [
                                        'end', 'm', 'start'
                                    ]
                                }
                            },
                            QueryString: true,
                            Headers: {
                                Quantity: 0
                            },
                            QueryStringCacheKeys: {
                                Quantity: 0
                            },
                        },
                        SmoothStreaming: true
                    }, {
                        MinTTL: 6,
                        PathPattern: '*',
                        TargetOriginId: targetOriginId,
                        ViewerProtocolPolicy: 'redirect-to-https',
                        AllowedMethods: {
                            Items: [
                                'GET', 'HEAD'
                            ],
                            Quantity: 2,
                        },
                        ForwardedValues: {
                            Cookies: {
                                Forward: 'whitelist',
                                WhitelistedNames: {
                                Quantity: 3,
                                Items: [
                                    'end', 'm', 'start'
                                ]
                                }
                            },
                            QueryString: true,
                            Headers: {
                                Quantity: 0
                            },
                            QueryStringCacheKeys: {
                                Quantity: 0
                            },
                        }
                    }]
                },
                PriceClass: 'PriceClass_All'
            }
        }
    }).promise()
  }
}

createDistributionForMediaPackage で作成したディストリビューションは、公式ページに記載された手順で作成した CloudFront ディストリビューションと同等のものになります。

詳細な説明はインラインコメントにて書きましたが、一応補足説明を少し付け加えておきます。

随所に出てくる `Quantity` について

Quantity には Items で指定する項目の数を入力します。 例えば Headers や QueryStringCacheKeys には Items に何も指定していないため、Quantity に 0 を指定します。

しかし、AllowedMethods や WhitelistedNames には Items に指定した項目数である 2 や 3 を Quantity に入力しています。Quantity の数と Items の項目数が合わないと、エラーが発生するため、注意が必要です。

`mediapackage:cloudfront_assoc` を定義する意味

CloudFront ディストリビューションのタグに mediapackage:cloudfront_assoc で紐付ける MediaPackage のチャンネル ARN を指定することで、MediaPackage コンソールから紐付けられた CloudFront ディストリビューション情報を参照できるようになります。

試しに紐づけられた MediaPackage のチャンネルのエンドポイント詳細ページに遷移すると、
下記のような画面が確認できるはずです。

mediapackage:cloudfront_assoc で紐付いた CloudFront ディストリビューションが確認できる

本記事内のソースコードでは他にも Id, Product, Stage といったタグを定義していますが、MediaPackage とは関係無いものなので削除して問題ありません。

`updateDistribution` を実行する際の注意点

これは今回の記事内容とは直接関係ないのですが、地味にハマったので載せておきます。

CloudFront では createDistribution の時に要求されるパラメータよりも updateDistribution で要求されるパラメータのほうが多いです。 AWS 公式ページの比較表にある通りです。

そのため、updateDistribution で設定を一部更新したいだけなのに、とても多くのパラメータを指定する必要があり非常に面倒です。例えば CloudFront ディストリビューションの Enable/Disable を切り替えるだけでも 30 個近いパラメータを指定する必要あります。

上記の入力の手間を省くのには getDistribution で取得した既存のディストリビューション情報を改変する形で updateDistribution のパラメータを作成すると楽でした。

今回のソースコードの内容を参照すると disableDistribution が該当します。

// 1. getDistribution を実行して CloudFront ディストリビューションの情報を取得する
const distribution = await this.getDistribution(id);

// 2. CloudFront ディストリビューションの設定内容を取得する
const config = distribution.Distribution.DistributionConfig;

// 3. CloudFront ディストリビューションの Enabled/Disabled を切り替えるオプションを改変する
config.Enabled = false;

// 4. 3. で改変した内容を updateDistribution で CloudFront ディストリビューションに反映する
return await this.cloudFront
  .updateDistribution({
    Id: id,
    IfMatch: distribution.ETag,
    DistributionConfig: config,
  })
  .promise();

おわりに

ニッチな内容なので、本記事内容を今後利用するかどうかは分かりませんが、一応得た知見を記事として残しておきました。同様のことを行う必要が出てきた方の参考になれれば幸いです。

参考リンク

[TECH] Actix web で HttpOnly な Cookie を設定する 🍪

nikaera — Sat, 20 Mar 2021 18:54:26 +0000

はじめに

最近 Rust を勉強するため、Actix web で Bloggimg という Web アプリケーションを作りました。その際、セッション管理のために Cookie を利用したのですが、その際の手順及び設定方法についてまとめておきます。

本記事では Rust や Actix web のインストール方法については説明しません。Mac であれば brew install rustup して rustup-init した後、PATH に $HOME/.cargo/bin を追加するだけで大丈夫なはずです。詳細なインストール手順については公式サイトをご参照ください。

開発環境については VSCode の Rust Plugin がオススメです。Rustup で Rust をインストールしている場合、設定から Rustup の PATH を $HOME/.cargo/bin/rustup にするだけで利用可能です。設定手順の詳細はこちらをご参照ください。

動作環境

Mac mini (M1, 2020)
- Rust 1.49
- Actix web 3
- Serde 1.0

[package]
name = "cookie_test"
version = "0.1.0"
authors = ["nikaera"]
edition = "2018"

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

[dependencies]
actix-web = "3"
serde = { version = "1.0", features = ["derive"] }

Actix web で Cookie をセットする

サーバー側で Cookie を設定するため、HTTP レスポンスヘッダーに Set-Cookie を含める形でセッション情報をクライアントへ渡します。その際、最低でも Cookie の属性に HttpOnly と Secure、SameSite=Strict は設定します。実際の Cookie を設定するための Actix web でのサンプルコードは下記になります。

use std::env;
use actix_web::{App, HttpServer};
use actix_web::cookie::{Cookie, SameSite};
use actix_web::{get, web, Error, HttpRequest, HttpResponse};

use serde::{Deserialize};

/// Cookie に設定するキー
/// 今回は cookie_test をキーとして使用する
///
const KEY: &str = "cookie_test";

/// 存在していれば、HTTP Request ヘッダーから Cookie 文字列を取得する関数
///
/// # Arguments
/// * `req` - actix_web::HttpRequest
///
/// # Return value
/// * Option<String> - key=value; key1=value1;~ のような Cookie の文字列
///
fn get_cookie_string_from_header(req: HttpRequest) -> Option<String> {
    let cookie_header = req.headers().get("cookie");
    if let Some(v) = cookie_header {
        let cookie_string = v.to_str().unwrap();
        return Some(String::from(cookie_string));
    }
    return None;
}

/// 存在していれば、特定のキーで Cookie に設定された値を取得するための関数
///
/// # Arguments
/// * `key` - Cookie から取り出したい値のキー
/// * `cookie_string` - get_cookie_string_from_header 関数で取得した Cookie の文字列
///
/// # Return value
/// * Option<String> - Cookie に設定されている値を取得する
///
fn get_cookie_value(key: &str, cookie_string: String) -> Option<String> {
    // 取得した Cookie 文字列を ; で分割してループで回す
    let kv: Vec<&str> = cookie_string.split(';').collect();
    for c in kv {
        // Cookie 文字列をパースして key で指定した値とマッチしたキーが存在するかチェックする
        match Cookie::parse(c) {
            Ok(kv) => {
                if key == kv.name() {
                    // key で指定した値とマッチしたキーが存在していたら、その値を取得する
                    return Some(String::from(kv.value()));
                }
            }
            Err(e) => {
                println!("cookie parse error. -> {}", e);
            }
        }
    }
    return None;
}

/// 特定のキーで環境変数から値を取得するための関数
///
/// # Arguments
/// * `key` - 環境変数から取り出したい値のキー
///
/// # Return value
/// * String - 環境変数の値を文字列として取得する
///
fn get_env(key: &str) -> String {
    match env::var(key) {
        Ok(value) => return value,
        Err(e) => println!("ENV: ERR {:?}", e),
    }
    return String::new();
}

/// 環境変数に設定された HTTPS の値が 1 か判定する
/// Cookie の属性に Secure を付与するか判定するのに使用する
///
/// # Return value
/// * bool - Secure 属性を付与するか判定するための真偽値
///
fn is_https() -> bool {
    return get_env("HTTPS") == "1";
}

/// Cookie に設定する値を扱う HTTP Query の定義
#[derive(Deserialize)]
pub struct CookieQuery {
    pub value: String,
}

/// Cookie を設定するために用意したルート
///
/// # Example
///
/// 例えば GET /cookie?value=test にアクセスした場合、
/// Cookie に cookie_test=test が設定されるようになる
///
#[get("/cookie")]
async fn set_cookie(query: web::Query<CookieQuery>) -> Result<HttpResponse, Error> {
    // 設定したい Cookie を作成する
    // その際に Secure, HttpOnly, SameSite=Strict 属性を付与する
    let cookie = Cookie::build(KEY, &query.value)
            .secure(is_https())
            .http_only(true)
            .same_site(SameSite::Strict)
            .finish();

    // 作成した Cookie を HTTP Response の Set-Cookie ヘッダーに含めることで、
    // HTTP Response を受け取ったクライアントに Cookie をセットさせる
    return Ok(HttpResponse::Ok()
        .header("Set-Cookie", cookie.to_string())
        .body(""));
}

/// KEY で指定した Cookie が存在すれば、その値を返却する
/// KEY で指定した Cookie が存在しなければ、空の文字列を返却する
#[get("/")]
async fn index(req: HttpRequest) -> Result<HttpResponse, Error> {
    let cookie_string = get_cookie_string_from_header(req);
    if let Some(s) = cookie_string {
        if let Some(v) = get_cookie_value(KEY, s) {
            return Ok(HttpResponse::Ok().body(v));
        }
    }
    return Ok(HttpResponse::Ok().body(""));
}

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    HttpServer::new(|| {
        App::new()
            .service(set_cookie)
            .service(index)
    })
    .bind("0.0.0.0:8080")?
    .run()
    .await
}

ザッとインラインコメントで説明していますが、

最も重要な set_cookie 関数について簡単に説明します。

Actix web には Cookie クラスが存在します。この Cookie クラスは Cookie 文字列を生成したり、パースしたりするのに役立ちます。set_cookie 関数では、Cookie を生成するための関数 Cookie::build を利用しています。

Cookie::build 関数を利用することで、メソッドチェインで Cookie の値や属性を設定できます。作成した Cookie は to_string 関数を使用することで文字列として出力できます。出力した Cookie 文字列を HTTP レスポンスヘッダーに Set-Cookie として設定すれば Cookie を設定できます。

動作検証

今回用意した Actix web のサンプルコードには 2 つのエンドポイントを用意しました。

URI	説明
`GET /cookie`	`value` クエリで HttpOnly な Cookie を設定する
`GET /`	`GET /cookie` で設定した Cookie を確認する

cargo run で Actix web のサンプルを起動した後に、ブラウザで http://localhost:8080/cookie?value=sample にアクセスしてみます。またその際に HTTP レスポンスヘッダーを確認したいため、開発者ツールを開いておきます。

HTTP レスポンスヘッダーに Set-Cookie が含まれていることを確認する

Set-Cookie が含まれていることが確認できたら正常に Cookie が設定されているか確認します。

HTTP リクエストヘッダーの Cookie に cookie_test=sample が存在していることを確認する

実際にブラウザーにも Cookie が正しく設定されているか、開発者ツールで確認する

正常に Cookie がセットされていることが確認できれば作業完了です。Cookie の属性に Secure を設定した場合の動作検証は、環境変数に HTTPS=1 をセットして cargo run で可能です。

おわりに

Actix web で割と汎用的に使えそうな知識として Cookie の設定方法について、メモ的な記事を書いてみました。引き続き、Rust への理解を深めるために Bloggimg の開発を進めながら学習を進めていきます 🧑‍🎓

本記事の内容がセキュリティの観点から適切でない場合等はコメントでご指摘いただけますと幸いです。

参考リンク

[TECH] Gatling で複数ユーザ認証した情報を元に負荷テストする 🔫

nikaera — Sat, 20 Mar 2021 18:54:16 +0000

はじめに

今までは JMeter でしか負荷テストを行ったことなかったのですが、最近 PlayFab で CloudFunction の負荷テストを行う際に Gatling を初めて利用しました。

今回の負荷テストでは、各ユーザ毎のレートリミットの制限等も考慮した実利用時を想定した形で行うことが要求されたため、単一ユーザの認証情報を使い回すことは望ましくないと考えました。そこで、複数の認証済みユーザの情報を元に PlayFab の CloudFunction の負荷テストを実施したのですが、若干実装に苦戦したため手順について記事として残しておくことにしました。

また、本記事では Gatling のセットアップから記載していますが、該当コードやその説明を早く見たいという方は 複数ユーザ認証を行うテストシナリオを実装する 項目をご参照ください。

動作環境

macOS Big Sur
Java OpenJDK 12.0.1
- 未インストールの方は事前に公式サイトから OpenJDK をインストールしてください

Gatling の環境を整える

Gatling には 2 種類のセットアップ方法が用意されています。 スタンドアローンなツールを直接公式サイトからダウンロードするか、Maven や sbt といったツール経由でダウンロードするか選択できます。

どちらの方法でセットアップするかについてですが、新規でテストケースを Gatling で書いていく用途だと前者になり、既存のプロジェクトに Gatling を取り込む用途だと後者になるかと存じます。

本記事では、前者のスタンドアローンなツールを直接公式サイトからダウンロードする方法で Gatling の環境をセットアップします。

公式サイトから Gatling をダウンロードする

Gatling のトップページに遷移して、ページを 2 Ways to use Gatling の項目までスクロールした後、ダウンロードボタンをクリックします。

DOWNLOAD GATLING'S BUNDLE にある DOWNLOAD NOW ボタンをクリックする

ファイルダウンロード後はダウンロードした zip ファイルを適当なフォルダに展開して配置します。
早速ターミナルで展開したフォルダ内にある ./bin/gatling.sh を実行して、正常にコマンドが実行できるか確認してみます。

OS が Windows の場合は ./bin/gatling.bat を実行します。

⊨ ./bin/gatling.sh                   ~/D/gatling-charts-highcharts-bundle-3.5.1
GATLING_HOME is set to /Users/nika/Desktop/gatling-charts-highcharts-bundle-3.5.1
Choose a simulation number:
     [0] computerdatabase.BasicSimulation
     [1] computerdatabase.advanced.AdvancedSimulationStep01
     [2] computerdatabase.advanced.AdvancedSimulationStep02
     [3] computerdatabase.advanced.AdvancedSimulationStep03
     [4] computerdatabase.advanced.AdvancedSimulationStep04
     [5] computerdatabase.advanced.AdvancedSimulationStep05
0 # 実行したいテストの番号を入力する、今回は適当に 0 を指定
Select run description (optional)
# 実行するテストに関する説明文を入力する。何も入力する内容が無い or
# 説明文の入力が完了したら Enter を入力して、実際にテストを実行する

# 選択したテストの実行が開始する
# (0 を入力したので computerdatabase.BasicSimulation が実行される)
Simulation computerdatabase.BasicSimulation started...

#...

Simulation computerdatabase.BasicSimulation completed in 26 seconds
Parsing log file(s)...
Parsing log file(s) done
Generating reports...

# テストの実行が無事完了すると、結果が表示されレポートファイルが生成される。
# レポート生成先のファイルパスは実行結果の末尾に表示される。
# レポートファイルは HTML で生成されるため、適当なブラウザで開くことで内容を確認することが出来る。

================================================================================
---- Global Information --------------------------------------------------------
> request count                                         13 (OK=13     KO=0     )
> min response time                                    230 (OK=230    KO=-     )
> max response time                                    483 (OK=483    KO=-     )
> mean response time                                   324 (OK=324    KO=-     )
> std deviation                                         98 (OK=98     KO=-     )
> response time 50th percentile                        259 (OK=259    KO=-     )
> response time 75th percentile                        415 (OK=415    KO=-     )
> response time 95th percentile                        476 (OK=476    KO=-     )
> response time 99th percentile                        482 (OK=482    KO=-     )
> mean requests/sec                                  0.481 (OK=0.481  KO=-     )
---- Response Time Distribution ------------------------------------------------
> t < 800 ms                                            13 (100%)
> 800 ms < t < 1200 ms                                   0 (  0%)
> t > 1200 ms                                            0 (  0%)
> failed                                                 0 (  0%)
================================================================================

Reports generated in 0s.
Please open the following file: /Users/nika/Desktop/gatling-charts-highcharts-bundle-3.5.1/results/basicsimulation-20210314133324259/index.html

./bin/gatling.sh を実行した後、上記のような出力が確認できれば、問題なくスタンドアローン版の Gatling 環境のセットアップが完了しています。

また、負荷テストのレポートを確認したい場合は、出力結果にある Please open the following file: <レポートのファイルパス> に記載されているファイルをブラウザで開きます。
html 拡張子を開くアプリのデフォルトが何らかのブラウザになっているのであれば、ターミナルから open <レポートのファイルパス> を実行するのでも構いません。

Gatling でテストシナリオを実装する

Gatling のテストシナリオを書く場所は ./user-files/simulations フォルダ内になります。 テストシナリオを Scala で書いた後、ファイルを ./user-files/simulations フォルダに配置します。すると、./bin/gatling.sh を実行した際の実行するテストシナリオのリストに出てくるようになります。

簡単なテストシナリオを試しに書いてみる

まずは試しに私のブログに対してのアクセス負荷を計測するためのテストを実装していきます。./user-files/simulations フォルダ内に nikaera.com フォルダを作成し、AccessSimulation.scala という負荷テストのシナリオファイルを作成します。

package com.nikaera

import scala.concurrent.duration._

import io.gatling.core.Predef._
import io.gatling.http.Predef._

import scala.collection.mutable.ListBuffer
import io.gatling.core.structure.PopulationBuilder

// 1. Simulation クラスを継承してテストシナリオを実行するクラスを定義する
class AccessSimulation extends Simulation {

  // 2. HTTP アクセスする際の設定値を入力する。
  // 今回はアクセス先のベース URL を定義するための baseUrl のみ指定
  val httpConf = http
    .baseUrl("https://nikaera.com")

  // 3. Scala の ListBuffer を用いて複数シナリオを格納する scenarios 変数を用意する
  val scenarios = new ListBuffer[PopulationBuilder]()

  // 4. httpConf で設定した情報を元に / (https://nikaera.com) 及び
  // /tech/ (https://nikaera.com/tech/) へ同時 10 アクセスするのを、
  // 5秒毎に 3回実行するシナリオを作成して、scenarios 変数に格納する
  val pollingApiScn = scenario("Polling Simulation")
    .exec(
      http("Top Page")
        .get("/")
        .check(status.is(200))
    )
    .exec(
      http("Tech Page")
        .get("/tech/")
        .check(status.is(200))
    )
  scenarios += pollingApiScn
    .inject(
      atOnceUsers(10),
      nothingFor(5 seconds),
      atOnceUsers(10),
      nothingFor(5 seconds),
      atOnceUsers(10)
    )
    .protocols(httpConf);

  // 5. 4. で定義したシナリオを実行して https://nikaera.com のアクセス負荷を計測する
  setUp(
    scenarios(0)
  )
}

再度 ./bin/gatling.sh を実行して、実際に負荷テストを行ってみます。

⊨ ./bin/gatling.sh                   ~/D/gatling-charts-highcharts-bundle-3.5.1
GATLING_HOME is set to /Users/nika/Desktop/gatling-charts-highcharts-bundle-3.5.1
Choose a simulation number:
     [0] com.nikaera.AccessSimulation
     [1] computerdatabase.BasicSimulation
     [2] computerdatabase.advanced.AdvancedSimulationStep01
     [3] computerdatabase.advanced.AdvancedSimulationStep02
     [4] computerdatabase.advanced.AdvancedSimulationStep03
     [5] computerdatabase.advanced.AdvancedSimulationStep04
     [6] computerdatabase.advanced.AdvancedSimulationStep05
0 # 作成したテストシナリオである com.nikaera.AccessSimulation を選択して実行します。
Select run description (optional)

Simulation com.nikaera.AccessSimulation started...

#...

Simulation com.nikaera.AccessSimulation completed in 10 seconds
Parsing log file(s)...
Parsing log file(s) done
Generating reports...

================================================================================
--------- Global Information --------------------------------------------------------
> request count                                         60 (OK=60     KO=0     )
> min response time                                     11 (OK=11     KO=-     )
> max response time                                    372 (OK=372    KO=-     )
> mean response time                                   104 (OK=104    KO=-     )
> std deviation                                         99 (OK=99     KO=-     )
> response time 50th percentile                         53 (OK=53     KO=-     )
> response time 75th percentile                        212 (OK=212    KO=-     )
> response time 95th percentile                        259 (OK=259    KO=-     )
> response time 99th percentile                        307 (OK=307    KO=-     )
> mean requests/sec                                  5.455 (OK=5.455  KO=-     )
--------- Response Time Distribution ------------------------------------------------
> t < 800 ms                                            60 (100%)
> 800 ms < t < 1200 ms                                   0 (  0%)
> t > 1200 ms                                            0 (  0%)
> failed                                                 0 (  0%)
================================================================================

Reports generated in 0s.
Please open the following file: /Users/nika/Desktop/gatling-charts-highcharts-bundle-3.5.1/results/accesssimulation-20210314144205502/index.html

テストシナリオの実行に成功していることが確認できたら、複数ユーザ認証した情報を元に行うテストシナリオを書いていきます。

複数ユーザ認証を行うテストシナリオを実装する

複数ユーザ認証するテストシナリオを実装していきます。PlayFab で複数ユーザの認証情報を元に CloudFunction の負荷テストを行うことを想定しています。¹ テストシナリオを作成するにあたり、./user-files/simulations/ フォルダに新たに playfab.com フォルダを作成して、その中に TestCloudFunctionSimulation.scala ファイルを生成します。

package com.playfab

import java.io._
import java.net.{HttpURLConnection, URL}
import io.gatling.core.Predef._
import io.gatling.http.Predef._
import scala.concurrent.duration._
import scala.util.Random
import scala.util.parsing.json.JSON
import scala.collection.mutable.ListBuffer
import io.gatling.core.structure.PopulationBuilder

class TestCloudFunctionSimulation extends Simulation {
  // PlayFab に登録されたユーザの ID 群
  val playfabUsers = Array[String](
    "user1",
    "user2",
    "user3",
    "user4",
    "user5",
    "user6",
    "user7",
    "user8",
    "user9",
    "user10"
  )

  // PlayFab の TitleId 及び Secret を変数に保持しておく
  val playfabId = "XXXXX"
  val playfabSecret = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  val playfabApiUrl =
    s"https://${playfabId}.playfabapi.com"

　// PlayFab の Login With Server Custom Id を利用して、
  // ユーザの認証情報を取得するために用いる関数
  def getPlayfabAuth(serverCustomId: String): Option[Any] = {
    val url = new URL(
      s"${playfabApiUrl}/Server/LoginWithServerCustomId"
    )
    val con = url.openConnection().asInstanceOf[HttpURLConnection]
    HttpURLConnection.setFollowRedirects(false)
    con.setRequestMethod("POST")
    con.setRequestProperty("Content-Type", "application/json")
    con.setRequestProperty("X-SecretKey", playfabSecret)
    con.setDoOutput(true)

    val out = new OutputStreamWriter(con.getOutputStream(), "UTF-8")
    out.write(s"""{
        "CreateAccount": false,
        "ServerCustomId": "${serverCustomId}"
    }""")
    out.flush()
    out.close()
    con.connect()

    val in = con.getInputStream

    val br = new BufferedReader(new InputStreamReader(in, "UTF-8"));
    val json = br.readLine()

    in.close()
    con.disconnect()

    return JSON.parseFull(json)
  }

  val httpConf = http
    .baseUrl(playfabApiUrl)
    .header("Content-Type", "application/json")

  // CloudFunction の Request Body を作成するために利用する関数
  def cloudScriptDto(funcName: String, funcArgs: String): String = {
    return s"""{
        "FunctionName": "${funcName}",
        "FunctionParameter": ${funcArgs}
    }"""
  }

  val scenarios: ListBuffer[PopulationBuilder] =
    new ListBuffer[PopulationBuilder]()

  playfabUsers.foreach(userId => {
    // playfabUsers で指定したユーザ ID 情報を元に、
    // PlayFab の認証情報を取得利用することで、
    val playfab = this.getPlayfabAuth(userId).get
    val map: Map[String, Option[Any]] =
      playfab.asInstanceOf[Map[String, Option[Any]]];

    // 愚直に JSON オブジェクトのパースを行い、必要な情報を変数に取り出す。
    val data = map.get("data").get.asInstanceOf[Map[String, Option[Any]]];
    val entityTokenInfo =
      data.get("EntityToken").get.asInstanceOf[Map[String, Option[Any]]];
    val entityToken =
      entityTokenInfo.get("EntityToken").get.asInstanceOf[String];

    val entity =
      entityTokenInfo.get("Entity").get.asInstanceOf[Map[String, Option[Any]]];
    val entityId =
      entity.get("Id").get.asInstanceOf[String];

    // Test2 API については CloudFunction 実行時のパラメタを、
    // ランダム指定したいため、Random を用いてパラメタを散らすようにする
    val rand = new Random
    val values = Array(
      "value1",
      "value2",
      "value3",
      "value4",
      "value5"
    )
    val values_length = values.length

    // アクセス負荷を調査したい CloudFunction API 群を実行する。
    val pollingApiScn = scenario(s"PollingSimulation: ${entityId}")
      .exec(
        http("Test1 Api")
          .post("/CloudScript/ExecuteFunction")
          .header("X-EntityToken", entityToken)
          .body(StringBody(cloudScriptDto("Test1", null)))
          .check(status.is(200))
      )
      .exec(
        http("Test2 Api")
          .post("/CloudScript/ExecuteFunction")
          .header("X-EntityToken", entityToken)
          .body(
            StringBody(
              cloudScriptDto(
                "Test2",
                s"""{"value": "${values(rand.nextInt(values_length))}"}"""
              )
            )
          )
          .check(status.is(200))
      );

    // 1 ユーザあたり 3秒毎に 100回ずつ API 群を実行した際の
    // 負荷テストのシナリオを scenarios 変数に格納する
    scenarios += pollingApiScn
      .inject(
        atOnceUsers(100),
        nothingFor(10 seconds),
        atOnceUsers(100),
        nothingFor(10 seconds),
        atOnceUsers(100)
      )
      .protocols(httpConf);
  });

  // scenarios 変数に格納されたテストシナリオを並列実行する
  setUp(
    scenarios(0),
    scenarios(1),
    scenarios(2),
    scenarios(3),
    scenarios(4),
    scenarios(5),
    scenarios(6),
    scenarios(7),
    scenarios(8),
    scenarios(9)
  )
}

ザッとインラインコメントで説明を書きましたが、重要な点についてのみ補足します。
def getPlayfabAuth は PlayFab 認証するための関数となっていますが、適宜認証に用いるサービス毎で関数の内容を変更することで、他サービスで認証するための関数として利用可能です。
また playfabUsers.foreach 内で各ユーザが実行するテストシナリオを生成しつつ、それらを scenarios 変数に保持しています。そうすることで、最後に setUp 関数でシナリオをまとめてセットできるようになります。

playfabUsers.foreach で値を指定するのではなく CSV でテストに与えるフィードデータを定義するする方法もあります。認証部分も含めてテストシナリオを書きたい場合にも便利に利用できます。またアカウント情報を CSV ファイルに定義しておくと、テストユーザの情報を新規追加したい場合で管理が楽になります。

上記テストシナリオのソースコードを応用することで、様々なサービスで複数ユーザ認証した情報を元に負荷テストを行うためのシナリオを作成することが可能となります。

おわりに

今回は Gatling で複数ユーザ認証した情報を元に負荷テストする手順について書きました。

Gatling で生成されるレポートは見やすく、改善点を洗い出してコードの改善作業をするのにとても有用でした。 また、JMeter と比べて動作が軽いため気軽に実行しやすく、テストシナリオが全てコードで管理されているためシナリオの改変も素早く行うことが出来ました。

個人的にはテストシナリオを全てコードで記述できる Gatling が気に入ったので今後も有効活用していきたいと感じました。ただ、Gatling 以外にも Python で書ける locust や JavaScript で書ける k6 など、他にも気になるツールがいくつかあったので今後試してみたいなと考えています。

勝手に負荷テストは JMeter 一択だと思っていたのですが、負荷テストツールには色々あるようなのでプロジェクトや自分にあったものを選定していけるよう随時キャッチアップしていきたいと感じました。

参考リンク

コードの setUp でシナリオを複数指定する箇所についてですが、より良いやり方があれば是非ご教授いただけますと幸いです... ↩

[TECH] Hugo + GitHub Pages + GitHub Actions で独自ドメインのウェブサイトを構築する 😊

nikaera — Sat, 20 Mar 2021 18:54:06 +0000

この記事は Static Site Generator Advent Calendar 2020 10 日目の記事です。

はじめに

Zenn や Qiita, note など様々なウェブサービスで記事を書くにつれて、ふと雑多な内容で自分の好き勝手に記事を書いて公開できる自分のブログが欲しくなりました。そこで、自分のブログを作ろうと思い調査したところ、SSG で作るのが手っ取り早そうだったのと、その中でも一番ラクにウェブサイトが構築できそうな Hugo を採用しました。

また、デプロイは簡単に行いたかったので、デプロイ先として GitHub Pages を採用しました。
独自ドメインの割り当てから HTTPS 対応まで無料でできるかつ、使い慣れている GitHub をデプロイ先に使えることが決め手でした。

Hugo で自分のブログを構築して GitHub Pages で公開できるようになったのですが、ブログ内容を更新したり記事を書くたびにビルドしてデプロイをするのが、意外と面倒なことに気づきました。そこで、GitHub Pages action を用いて、ビルドしてデプロイするという作業は自動化しました。

上記までの作業をすることで、自分のブログを書いたり更新することだけに集中できる環境を整えることができました。ウェブサイトを作りこむ以外は、簡単ないくつかの作業をするだけで Hugo で満足のいく自分のブログを書く環境が整えられたので、その手順についてまとめてみました。

ちなみに本記事の手順で実際に作成した私のブログは下記です。

https://nikaera.com/

Hugo を PC にインストールする

私は Windows には Chocolatey、Mac では Homebrew で Hugo をインストールしました。Chocolatey や Homebrew を利用したインストール方法については公式サイトの手順で公開されています。

# Mac で Homebrew を使って Hugo をインストールする
brew install hugo

# Windows で Chocolatey を使って Hugo をインストールする
choco install hugo -confirm

# Sass/SCSS を用いてウェブサイトのデザイン改修を行いたい場合は
# 下記で Chocolatey を使って Hugo をインストールする
choco install hugo-extended -confirm

Hugo で自分のウェブサイトを構築する

Hugo プロジェクトを作成する

下記コマンドで Hugo のプロジェクトフォルダを生成できます。

hugo new site <プロジェクトフォルダのパス>

Hugo のコンフィグファイルのデフォルトフォーマットは TOML 形式なのですが、hugo new site <プロジェクトフォルダへのパス> -f json のように -f オプションを付与することで JSON フォーマットでもコンフィグファイルを生成可能です。

後述しますが、一部の Hugo のテーマはコンフィグファイルのサンプルが JSON ファイルで書かれています。その場合は、新規で設定するコンフィグファイルのフォーマットも JSON で統一しておくと各種設定項目の調整が楽になりそうです。

もしくはこちらのようなコンバーターを使用したり、こちらのようなウェブのコンバーターを使用して、設定ファイルを JSON から TOML フォーマットに変更しても良さそうです。

ウェブサイトのテーマを探す

テーマとは、ウェブサイトのデザインテンプレートのことです。テーマは Hugo Themes で公開されているので、この中から自分の好みを選びます。Hugo ではテーマの内容をカスタマイズしたり差し替えることもできるので、あとから一部デザインを自分好みに修正できます。

Hugo Themes にアクセスした時のページ

お気に入りのテーマが見つかったら、Download ボタンをクリックしてテーマの GitHub URL を控えておきます。

Kiera というテーマのページ

Hugo プロジェクトにテーマを適用する

テーマの適用方法については公式サイトの手順で紹介されていますが、Hugo のプロジェクトフォルダのルートで下記コマンドを実行して、コンフィグファイルに theme を追記するだけです。

git clone <テーマの GitHub URL> themes/<テーマ名> --depth=1
echo 'theme = "<テーマ名>"' >> config.toml

どのテーマも基本的に適用方法は同じで、例えば私が採用したテーマである PaperMod を適用する場合は下記コマンドを実行することになります。

git clone https://github.com/adityatelange/hugo-PaperMod themes/hugo-PaperMod --depth=1
echo 'theme = "hugo-PaperMod"' >> config.toml

これで自分のウェブサイトを作り込んでいくための準備が整いました。

ウェブサイトを作り込む

各テーマには exampleSite というウェブサイト作成の参考になる Hugo のプロジェクトフォルダが存在します。 最初は exampleSite フォルダ内に存在する各種ファイルを自分のプロジェクトにコピー&ペーストして、改変しながらウェブサイトを作り込んでいくとスムーズに作業が進められます。

exampleSite フォルダは大抵 GitHub プロジェクトのルートに存在しているのですが、GitHub のブランチで管理しているものもあります。 私の採用した PaperMod は GitHub の exampleSite ブランチで管理していました。

上記のような詳細は Hugo のテーマページに記載があるはずなので、事前に exampleSite フォルダが配置されている場所や設定可能な項目等をチェックしておくことをオススメします。実際のウェブサイトの見た目を確認するには、Hugo のプロジェクトフォルダのルートで下記コマンドを実行します。

hugo server

hugo server 実行中に、ウェブサイトの設定を変更したり記事を追加すると、自動的にビルドが実行されるので常に最新のウェブサイトの見た目を確認できます。また、その際にエラーもコンソールに出力されるので、適宜修正しながらウェブサイトの作成を進めていくことが可能です。

GitHub にデプロイ環境を整える

ウェブサイトの構築が出来ればあとはデプロイするだけです。今回は GitHub Actions でデプロイするため、残りの作業は GitHub 上で進めていきます。一応 GitHub Actions を使わずに手動でデプロイする手順については、Hugo の公式サイトの手順にて紹介されています。

GitHub Actions を用いてデプロイできるようにした際の利点としては下記があります。

デプロイ時に毎回手動で複数コマンド実行する手間が省ける
自動化することでデプロイ時のコマンドミスを防ぐことが可能
常に統一した Hugo のビルド環境が利用可能

最初のうちは私も公式サイトの手順通りに Mac で手動デプロイしていました。しかし、Windows 環境でデプロイ作業した際、本番環境デプロイ時に SRI 関連のエラーが発生してしまい、ウェブサイトに stylesheet が適用されないバグが発生してしまいました。

結局原因はよく分からなかったのですが、GitHub Actions 経由でデプロイするようにしたところ直りました。CI 経由でデプロイできるようになると、こういった実行環境の違いによる挙動も気にする必要が無くなります。

一応 Windows 環境で発生した SRI 関連のバグは Hugo で該当するテンプレートファイルを layouts フォルダを利用して差し替えて、integrity の設定内容を空にすることで、本番環境でも stylesheet が適用できるようになったことは確認しました。詳細はこちら。

自分のウェブサイトをデプロイするためのリポジトリを作成する

GitHub の公式サイトの手順に従って、自身のウェブサイトをデプロイするためのリポジトリを作成します。また本記事では、Hugo プロジェクトのリポジトリはデプロイ用リポジトリとは別で扱うため、Hugo プロジェクトのリポジトリも新たに作成します。

本記事では Hugo プロジェクトのリポジトリ名は hugo-blog という名前に設定した前提で進めていきます。また作成したリモートリポジトリの情報は、下記コマンドで Hugo プロジェクトに登録しておきます。

# Hugo プロジェクトフォルダのルートで Git リポジトリを作成する
git init

# Hugo プロジェクトのリポジトリ情報を登録しておく (hugo-blog の GitHub URL)
git remote add origin <Hugo プロジェクトのリポジトリの URL>

GitHub Actions で Hugo のビルドからデプロイまでを自動化するための環境を整える

今回は hugo-blog という Hugo プロジェクトのリポジトリから、デプロイ用リポジトリへデプロイしたいため、まずはデプロイ用リポジトリでデプロイキーを登録します。公式サイトの手順に従いデプロイキーを登録したら、秘密鍵を hugo-blog リポジトリのシークレットに登録します。

シークレットは公式サイトの手順に従って登録します。今回は秘密鍵をシークレットに登録する際の名前に ACTIONS_DEPLOY_KEY を設定した前提で進めていきます。

次に GitHub Pages action を導入して Hugo のビルドから公開までを自動化する環境をセットアップします。

hugo-blog リポジトリに GitHub Pages action の Getting started を参考にワークフローファイルを追加します。- name: Deploy の項目のみデプロイ用リポジトリへデプロイするために設定内容を変更します。

name: github pages

on:
  push:
    branches:
      - main  # Set a branch name to trigger deployment

jobs:
  deploy:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/checkout@v2
        with:
          submodules: true  # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: '0.78.2'

      - name: Build
        run: hugo --minify

    #   - name: Deploy
    #     uses: peaceiris/actions-gh-pages@v3
    #     with:
    #       github_token: ${{ secrets.GITHUB_TOKEN }}
    #       publish_dir: ./public
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
          external_repository: nikaera/nikaera.github.io
          publish_branch: main
          cname: nikaera.com

- name: Deploy の項目で設定した各種パラメータは下記になります。

キー	説明
deploy_key	デプロイ時に使用する秘密鍵
external_repository	デプロイ先のリモートリポジトリ
publish_branch	デプロイ先のリモートリポジトリのブランチ
cname	設定するカスタムドメイン名

deploy_key にはシークレットに登録した秘密鍵を設定します。external_repository には Hugo をビルドした際のデプロイ先リポジトリを <ユーザ名>/<リポジトリ名> のフォーマットで指定します。publish_branch はデプロイ先として使用するブランチ名になります。cname には自分が設定したいドメイン名を指定します。cname の詳細はこちらからご確認いただけます。

カスタムドメインで設定した内容で DNS 設定を書き換える

GitHub Pages にカスタムドメインを利用する際は、該当するドメインの DNS レコードの設定で CNAME レコードもしくは A レコードを設定する必要があります。公式サイトの手順に従って設定します。

また、カスタムドメインの設定後は特別な理由がない限りは、デプロイ用リポジトリで HTTPS 強制の設定をしておくことオススメします。

ちなみに GitHub Pages で利用している証明書は Let's Encrypt のものになります。

設定作業はこれで完了です。あとは実際に Hugo プロジェクトを更新後、hugo-blog リポジトリに push することでビルドからデプロイまで GitHub Actions で行われるようになったかを確認していきます。

Hugo プロジェクトの更新時に自動でデプロイが行われるか確認する

Hugo プロジェクトには既に hugo-blog リポジトリの GitHub URL が origin として設定されているはずなので、下記で実際に hugo-blog リポジトリへ push してみます。

# Hugo プロジェクトを hugo-blog リポジトリに push する
git add -A
git commit -m "initial commit"
git push origin main

次は実際に GitHub リポジトリの Actions タブから、GitHub Pages action のワークフローが実行されているか確認します。

GitHub Pages actions の実行に成功した様子

無事ワークフローの実行に成功したことを確認したら、デプロイ用リポジトリの様子を確認します。

デプロイ用リポジトリに Hugo の最新ビルドが push されていることを確認する

最新コミットのメッセージに deploy: <ユーザ名>/hugo-blog@<コミットハッシュ> のコメントが表示されているはずです。コメントのリンクをクリックすると、hugo-blog リポジトリの最新コミットの確認画面に遷移するはずです。

ここまで確認できれば、あとはローカルで hugo server して確認していたウェブサイトと同じように、GitHub Pages 上でもウェブサイトが見えるか実際に確認してみます。

デプロイ用リポジトリ名が <ユーザ名>/<ユーザ名>.github.io であった場合、https://<ユーザ名>.github.io でウェブサイトにアクセスできます。私の場合は https://nikaera.github.io になります。その際、カスタムドメインにリダイレクトすることも確認できれば、カスタムドメインの設定も正常に反映されています。

ページが正常に表示されていてカスタムドメインでアクセスできた様子

アクセス時に意図したページが表示されていることが確認できれば大丈夫です。これで自分のウェブサイトを更新したら hugo-blog リポジトリに Hugo プロジェクトを push するだけで自分のウェブサイトを自動更新できるようになりました。

おわりに

今回は Hugo を例にしましたが、本記事内で紹介した GitHub Pages action は様々な SSG に対応しています。そのため Hugo ではウェブサイトのカスタマイズに限界が来たなと感じたら Next.js や Gatsby に乗り換えるといったことも可能です。

また Hugo では何も考えずとも、マークダウンで記事が書けてビルドも高速なので、手っ取り早く自分のウェブサイトを構築してみたいという用途にはピッタリだと感じました。

関係ないですが、Hugo でウェブサイト構築する際の知見も記事に含めてしまったせいで、文章量が意図した倍近い量になってしまいました。。簡潔で分かりやすい文章が書けるようにならなきゃ。。

参考リンク

[TECH] Hugo で React + TypeScript を利用してサクッとウェブサイトに RSS リーダーを追加する ⛳

nikaera — Sat, 20 Mar 2021 18:53:55 +0000

この記事は Static Site Generator Advent Calendar 2020 22 日目の記事です。

はじめに

Hugo のウェブサイトに組み込む RSS リーダーを TypeScript で開発してみたいと思い調査したところ、Hugo の最新版には ESBuild が組み込まれていて、非常に手厚く JavaScript の開発環境がサポートされていることが分かりました。 本記事では紹介していませんが Babel も利用できるようです。

また、NPM パッケージも利用できるため、普段のウェブ開発と同様の流れで開発ができ、各種ライブラリを用いた開発も非常に楽でした。
今回は Hugo で JavaScript 開発する方法を RSS リーダーの開発を例に上げ、そこで得た知見についても交える形で記事として残しておくことにしました。

ちなみに本記事内容は Hugo で JavaScript 開発する方法に焦点を絞ったものなのですが、ウェブサイトに RSS リーダーを組み込むことに焦点を絞って見たい方は RSS リーダーを Hugo の Data Templates で実装する から見ていただくことをオススメします。

Hugo で JavaScript (React + TypeScript) の開発環境を整える

まず、TypeScript のビルドは ESBuild に任せることができるため何も行う必要はありません。 そのため React 開発用パッケージのインストールのみ行えば大丈夫です。

Hugo プロジェクトのルートディレクトリで下記コマンドを実行し、package.json を作成してから、React の開発に必要なパッケージをインストールします。

npm init -y
npm install --save react react-dom

無事パッケージのインストールが完了したら、早速 TSX ファイルを assets/js/App.tsx に作成してしまいます。

import * as React from "react";
import * as ReactDOM from "react-dom";

function App() {
    return (
        <>
        Hello React!
        </>
    );
}

ReactDOM.render(
    <App />,
    document.getElementById("react")
);

上記のコードを見てもらえば分かる通り、レンダリング先に id が react の DOM ノードを指定しています。そのため Hugo 側で該当する DOM ノードを用意する必要があります。その際の HTML テンプレートは下記になります。

<!-- ... -->

<!-- 利用するリソースを指定する -->
{{ with resources.Get "js/App.tsx" }}

<!-- id が react の div 要素を用意する -->
<div id="react"></div>

<!-- TSX を ESBuild でビルドする際の Hugo のオプションを指定する -->
{{ $options := dict "targetPath" "js/app.js" "minify" true "defines" (dict
"process.env.NODE_ENV" "\"development\"") }}

<!-- TSX のビルドを Hugo のオプションで指定した内容で実行する -->
{{ $js := resources.Get . | js.Build $options }}

<!-- 一応 SRI を有効化した状態でビルドした JS を読み込む -->
{{ $secureJS := $js | resources.Fingerprint "sha512" }}
<script
  src="{{ $secureJS.Permalink }}"
  integrity="{{ $secureJS.Data.Integrity }}"
></script>

{{ end }}

<!-- ... -->

ちなみに $options で指定している ESBuild でビルド時に指定可能なオプションは Hugo の公式ページに記載されています。

上記 HTML の記述を RSS リーダーを埋め込みたいページに追加します。
この状態で該当ページにアクセスすると下記のような表示が確認できるはずです。

App.tsx で定義した内容が画面に表示される

これで React + TypeScript の開発環境が整いました。

RSS リーダーを実装する

あとは一般的な Web フロントエンド開発の流れで RSS リーダーの開発を進めていくだけです。

ウェブサイトで読み込みたい RSS フィードを準備する

RSS フィードを利用する際は必ず提供しているサービスの利用規約をご確認ください。
Qiita 及び Zenn については個人利用かつ自分の情報のみを扱う範囲内であれば利用が許可されているように見受けられました。¹

下準備としてウェブサイトで読み込みたい RSS フィードを事前にダウンロードするためのバッチを作成します。バッチは NPM を利用して作成していきます。NPM を導入したので Hugo で利用する簡易なバッチは JavaScript でサクッと作成していきます。

まずはスクリプト作成の際に必要となるパッケージを事前にいくつかインストールします。

# html をテキスト変換にするパッケージと RSS フィードのパーサーをインストールする
npm i -D --save html-to-text rss-parser

実際のコードは下記になります。ファイル名末尾が .mjs なのは Top-Level Await を使用したいからです。

import { writeFileSync } from 'fs';

import pkg from 'html-to-text';
const { htmlToText } = pkg;

import Parser from 'rss-parser';
const parser = new Parser();

// 自ブログで読み込みたい RSS フィードの情報を設定する
const rssFeed = {
    Zenn: {
        rss_url: 'https://zenn.dev/nikaera/feed',
        profile_url: 'https://zenn.dev/nikaera',
    },
    Qiita: {
        rss_url: 'https://qiita.com/nikaera/feed.atom',
        profile_url: 'https://qiita.com/nikaera',
    }
}

try {
    const jsonFeed = {}

    // RSS フィード内の description を 73字で切り取り末尾に ... を付与する関数
    const spliceContent = (content) => `${htmlToText(content).slice(0, 73)}...`

    // rssFeed 変数で定義されてる情報を繰り返し処理する
    for (const [site, info] of Object.entries(rssFeed)) {

        // RSS フィードの URL から必要な情報を取得する
        const feed = await parser.parseURL(info.rss_url);

        // RSS フィードに登録されている項目で必要な情報のみを取得する
        const items = feed.items.map((i) => {
            return {
                title: i.title,
                content: spliceContent(i.content),
                url: i.link,
                date: i.pubDate
            }
        })

        // 取得内容は jsonFeed に格納する
        const { rss_url, profile_url } = info
        jsonFeed[site] = { rss_url, profile_url, items };
    }

    // 最後に jsonFeed に格納された内容を JSON 文字列として static/rss.json に出力する
    writeFileSync('./static/rss.json', JSON.stringify(jsonFeed));
} catch(err) {
    console.error(err);
}

次に package.json の scripts に登録してコマンドとして実行可能にします。

{
    "scripts": {
        "update-rss": "node ./scripts/update-rss.mjs"
    }
}

これで npm run update-rss を実行すれば自ブログで表示する際に用いる JSON ファイルとして RSS フィードの内容を static/rss.json に出力できます。また、JSON ファイルは static フォルダに出力しているため http://localhost:1313/rss.json でアクセスできます。

npm run update-rss を実行して出力した rss.json

http://localhost:1313/rss.json にアクセスして出力した rss.json が参照可能なことを確認する

RSS リーダーを React + TypeScript で実装する

準備が整ったので、早速 RSS リーダーを作成していきます。

下記は Hugo のテーマの 1 つである hugo-PaperMod の archives テンプレートを利用してページに埋め込むことを想定した RSS リーダーのコードです。

import React, { useMemo, useState } from 'react'

import * as superagent from 'superagent';

const Rss = (props) => {
    const [feed, setFeed] = useState({});
    const { name } = props;

    useMemo(() => {
        (async () => {
            try {
                const res = await superagent.get('/rss.json');
                setFeed(res.body[name]);
            } catch (err) {
                console.error(err);
            }
        })()
    }, [name]);

    if (!("items" in feed)) return null

    return (
        <div className="archive-month">
            <h3 className="archive-month-header">
                <a href={feed.profile_url} target="_blank" rel="noopener noreferrer">{name}</a> - <a href={feed.rss_url} target="_blank" rel="noopener noreferrer">RSS</a>
            </h3>
            <div className="archive-posts">
                {feed.items.map((item) => {
                    return <div className="archive-entry" key={item.url}>
                        <h3 className="archive-entry-title">{item.title}</h3>
                        <div className="archive-meta">{item.date} - {item.content}</div>
                        <a className="entry-link" href={item.url} target="_blank" rel="noopener noreferrer">&nbsp;</a>
                    </div>
                })}
            </div>
        </div>
    )
}

export default Rss

次に assets/js/App.tsx で assets/js/Rss.tsx を読み込み画面に表示できるよう改修します。

import Rss from './Rss';

import * as React from "react";
import * as ReactDOM from "react-dom";

function App() {
    return (
        <>
            <div class="archive-year">
                <h2 class="archive-year-header">
                    Tech 🦾
                </h2>
                <Rss name="Zenn" />
                <Rss name="Qiita" />
            </div>
        </>
    );
}

ReactDOM.render(
    <App />,
    document.getElementById("react")
);

これで RSS リーダーを埋め込んだページを閲覧すると下記のような画面が表示されるはずです。

hugo-PaperMod で archives テンプレートを用いて RSS リーダーを表示したときの画面

もし他の RSS フィードを追加したい場合は scripts/update-rss.mjs の rssFeed 変数に情報を追加して、App.tsx に <Rss name="<rssFeed 変数で定義した RSS Feed 名>" /> を定義することで対応できます。

RSS フィードの内容を自動で更新する

npm run update-rss を手元で実行して static/rss.json を更新して公開すれば、最新の RSS フィードの内容をページに反映できる状態ですが、都度手動で更新するのは面倒な作業です。

そこで今回は GitHub Actions の schedule を用いて static/rss.json の更新を自動化します。

GitHub Actions のワークフローファイルを作成する

実際のワークフローファイルは下記になります。schedule の項目で設定している内容がワークフローの実行スケジュールになります。今回は半日毎に更新が走るようにしました。

name: update rss json file

on:
  push:
    branches:
      - main  # Set a branch name to trigger deployment
  schedule:
    - cron: '0 */12 * * *' # 今回は半日に 1回のタイミングで更新するようにした

jobs:
  build:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/checkout@v2
        with:
          ref: main
          submodules: true  # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

      - name: Use Node.js 14.10.1
        uses: actions/setup-node@v1
        with:
          node-version: 14.10.1

      - name: Install dependencies
        run: npm install

      - name: Update RSS Feeds
        run: npm run update-rss

      - name: Commit files
        run: |
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"
          git add static/rss.json
          STATUS=$(git status -s)
          if [ -n "$STATUS" ]; then
            git commit -m "Update rss.json `date +'%Y-%m-%d %H:%M:%S'`" -a
            git push origin main
          fi

上記ワークフローファイルをプロジェクトに追加して、リモートリポジトリにプッシュした後は、ワークフローが実行されるタイミングを待ちます。

無事にワークフローの実行が完了すると下記のようなコミットが追加されているはずです。

GitHub Actions が JSON ファイルを更新してコミットしている

コミットの詳細を見ると正常に JSON ファイルが更新されていることが確認できる

コミット後 Hugo をビルド & デプロイするとページが更新されていることを確認できる

これで Zenn や Qiita 等に記事を書いた際に、都度手動で static/rss.json を更新してページに最新の内容を反映させる作業は必要なくなりました。

(余談) RSS リーダーを Hugo の Data Templates で実装する

ちなみに Hugo には Data Templates という仕組みがあり、これを用いることで実は JavaScript を利用しなくても HTML テンプレートで RSS リーダーを実現できるということを後から知りました。

そこで最後に Data Template での RSS リーダーの実装方法について記載します。

まずは、scripts/update-rss.mjs の内容を書き換えます。

import { writeFileSync } from 'fs';

import pkg from 'html-to-text';
const { htmlToText } = pkg;

import Parser from 'rss-parser';
const parser = new Parser();

const rssFeed = {
    Zenn: {
        rss_url: 'https://zenn.dev/nikaera/feed',
        profile_url: 'https://zenn.dev/nikaera'
    },
    Qiita: {
        rss_url: 'https://qiita.com/nikaera/feed.atom',
        profile_url: 'https://qiita.com/nikaera'
    }
}

try {
    const jsonFeed = {}

    const spliceContent = (content) => `${htmlToText(content).slice(0, 73)}...`
    for (const [site, info] of Object.entries(rssFeed)) {
        const feed = await parser.parseURL(info.rss_url);
        const items = feed.items.map((i) => {
            console.log(i);
            return {
                title: i.title,
                content: spliceContent(i.content),
                url: i.link,
                date: i.pubDate
            }
        })
        const { rss_url, profile_url } = info
        jsonFeed[site] = { rss_url, profile_url, items };

        /*
        最終的な JSON ファイルの出力先は data フォルダとなり、RSS フィード毎に出力する
        例: ./data/Qiita.json, ./data/Zenn.json, etc.
        */
        writeFileSync(`./data/${site}.json`, JSON.stringify(jsonFeed[site]));
    }
} catch(err) {
    console.error(err);
}

上記を実行することで data/Qiita.json や data/Zenn.json にファイルが出力されます。

Hugo の Data Template を用いると data フォルダ内に配置した json, yaml, toml 形式のファイルは Go の HTML テンプレートで読み込めるようになります。

例えば、data/Qiita.json に配置された JSON ファイルを読み込みたい場合は Go のテンプレートで $Qiita := $.Site.Data.Qiita のような記述でできます。

次に RSS リーダーを埋め込んでいたページを下記のように書き換えます。

<!-- ... -->

<!-- React 関連の記述を全て削除する -->
<!--
{{ with resources.Get "js/App.tsx" }}
<div id="react"></div>
{{ $options := dict "targetPath" "js/app.js" "minify" true "defines" (dict "process.env.NODE_ENV" "\"development\"") }}
{{ $js := resources.Get . | js.Build $options }}
{{ $secureJS := $js | resources.Fingerprint "sha512" }}
<script src="{{ $secureJS.Permalink }}" integrity="{{ $secureJS.Data.Integrity }}"></script>
{{ end }}
-->

<div class="archive-year">
  <h2 class="archive-year-header">Tech 🦾</h2>
  <div class="archive-month">
    <!-- data/Zenn.json の内容を読み込む -->
    {{ $Zenn := $.Site.Data.Zenn }}
    <h3 class="archive-month-header">
      <a
        href="{{ $Zenn.profile_url }}"
        target="_blank"
        rel="noopener noreferrer"
        >Zenn</a
      >
      -
      <a href="{{ $Zenn.rss_url }}" target="_blank" rel="noopener noreferrer"
        >RSS</a
      >
    </h3>
    <div class="archive-posts">
      <!-- 配列で格納されている記事情報を繰り返し処理で取得する -->
      {{- range $Zenn.items }}
      <div class="archive-entry" key="{{ .url }}">
        <h3 class="archive-entry-title">{{ .title }}</h3>
        <div class="archive-meta">{{ .date }} - {{ .content }}</div>
        <a
          class="entry-link"
          aria-label="{{ .content }}"
          href="{{ .url }}"
          target=" _blank"
          rel="noopener noreferrer"
        ></a>
      </div>
      {{- end }}
    </div>
  </div>
  <div class="archive-month">
    <!-- data/Qiita.json の内容を読み込む -->
    {{ $Qiita := $.Site.Data.Qiita }}
    <h3 class="archive-month-header">
      <a
        href="{{ $Qiita.profile_url }}"
        target="_blank"
        rel="noopener noreferrer"
        >Qiita</a
      >
      -
      <a href="{{ $Qiita.rss_url }}" target="_blank" rel="noopener noreferrer"
        >RSS</a
      >
    </h3>
    <div class="archive-posts">
      <!-- 配列で格納されている記事情報を繰り返し処理で取得する -->
      {{- range $Qiita.items }}
      <div class="archive-entry" key="{{ .url }}">
        <h3 class="archive-entry-title">{{ .title }}</h3>
        <div class="archive-meta">{{ .date }} - {{ .content }}</div>
        <a
          class="entry-link"
          aria-label="{{ .content }}"
          href="{{ .url }}"
          target=" _blank"
          rel="noopener noreferrer"
        ></a>
      </div>
      {{- end }}
    </div>
  </div>
</div>

<!-- ... -->

また GitHub Actions のワークフローを用いて RSS フィードの情報を更新していた場合は、.github/workflows/update-rss.yml ファイルの更新も必要になります。

name: update rss json file

on:
  push:
    branches:
      - main  # Set a branch name to trigger deployment
  schedule:
    - cron: '0 */12 * * *'

jobs:
  build:
    runs-on: ubuntu-18.04
    steps:
      - uses: actions/checkout@v2
        with:
          ref: main
          submodules: true  # Fetch Hugo themes (true OR recursive)
          fetch-depth: 0    # Fetch all history for .GitInfo and .Lastmod

      - name: Use Node.js 14.10.1
        uses: actions/setup-node@v1
        with:
          node-version: 14.10.1

      - name: Install dependencies
        run: npm install

      - name: Update RSS Feeds
        run: npm run update-rss

        # Git で追加する内容を data フォルダに変更する
        # git add static/rss.json -> git add data/
      - name: Commit files
        run: |
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"
          git add data/
          STATUS=$(git status -s)
          if [ -n "$STATUS" ]; then
            git commit -m "Update data folder `date +'%Y-%m-%d %H:%M:%S'`" -a
            git push origin main
          fi

これで JavaScript で作成した RSS リーダーから、Hugo の Data Templates を用いて作成した RSS リーダーへ移行できました。

おわりに

Hugo で React + TypeScript 開発を楽にできそうなことが分かり、テンションが上がってしまい、そのままのノリで実際に RSS リーダーを自ブログ向けに作成してみました。

しかし、本記事内容で RSS リーダーを実装するのであれば、Hugo の Data Templates を利用することがベストなことに後から気づきました。ただ Hugo での JavaScript を用いた開発手法が理解でき勉強になったので結果ヨシとしました。

Hugo での JavaScript 開発環境は相当充実していることが分かったので、また何かアイデアを思いついたら気軽に作って自ブログに取り込んでいきます。今はザックリ WebGL/WebVR とかで何か面白いもの作れそうだなと考えています。

参考リンク

もし認識に誤りがあればコメント欄等でご教授いただけますと幸いです。 ↩

Forem: nikaera

[TECH] OpenNext + Drizzle で Cloudflare D1 環境を最も楽に構築する 🌧️

はじめに

動作環境

プロジェクト構成

1. 必要なパッケージのインストール

2. Cloudflare D1 の設定

値の確認・発行方法

3. 環境別のデータベース設定

4. データベーススキーマの定義

5. テスト環境の構築

6. テストの実装

実際の開発フロー

1. DB のローカル環境構築

2. DB の本番環境への反映

まとめ

参考リンク

[IDEA] Flutter で本格的な HTTP キャッシュライブラリ「AeroCache」を作ってみた ☁️

はじめに

HTTP のプライベートキャッシュの仕組み

主要な Cache-Control ディレクティブの対応

ETag や Last-Modified による効率的な再検証

Vary による条件付きキャッシュ

おわりに

参考リンク

[TECH] ECS Fargate のメトリクスを Prometheus Agent 使って AMP に送って Grafana で監視する 🔥

はじめに

動作環境

環境構築

AWS CDK で環境構築する

ECS Fargate で動かす Node.js アプリを準備する

Node.js アプリを監視する Prometheus Agent を準備する

ECS Fargate 上で Node.js アプリおよび Prometheus Agent を動作させる

Grafana で Prometheus (AMP) のメトリクスを可視化する

おわりに

参考リンク

[TECH] Unity で iOS/Android アプリの設定値をセキュアに扱う方法 🔑

はじめに

動作環境

Android のネイティブプラグインを作成する

(追記) Gradle を利用したライブラリのインストール方法

External Dependency Manager for Unity で必要なパッケージをインストールする

EncryptedSharedPreferences を利用するためのネイティブコードを追加する

iOS のネイティブプラグインを作成する

Keychain Services を利用するためのネイティブコードを追加する

(余談) インターフェースで iOS/Android のふるまいを共通化する

おわりに

参考リンク

[TECH] GameCI で Unity の CI 環境を GitHub Actions で構築する 🎮

はじめに

GameCI に備わっている機能紹介

Activation: GameCI で必要となる Unity License のアクティベーションを行う

Test runner: PlayMode 及び EditMode テストを実行して結果を参照する

Builder: プロジェクトのビルドを実行して出力結果を確認する

Returning a license: GameCI で利用している Unity License を返却する

おわりに

参考リンク

[TECH] Zenn の記事を DEV に自動的に同期させる GitHub Actions 作ってみた 📌

はじめに

開発した GitHub Actions の概要

Zenn の記事を DEV に同期するための仕組み

GitHub Actions を開発する手順

TypeScript で GitHub Actions を作る

GitHub Actions プロジェクトの開発を進めるための準備を行う

GitHub Actions を実装する際に利用した機能

作成した GitHub Actions を実際に GitHub 上で実行可能にする

Zenn の全ての記事を DEV に同期するためのワークフロー

更新差分のあった Zenn 記事のみを DEV に同期するためのワークフロー

おわりに

参考リンク

[TECH] AWS Lightsail Containers に Actix web をデプロイする ⛵

はじめに

Actix web の Docker イメージを作成する

Docker Hub にビルドしたイメージを push する

AWS Console から Lightsail Containers Service を作成する

(おまけ) 独自ドメインで Container Service へアクセス可能にする

おわりに

参考リンク

[TECH] MediaPackage 用の CloudFront ディストリビューションを AWS SDK で作成する 🎥

はじめに

主要な `Cache-Control` ディレクティブの対応

随所に出てくる `Quantity` について

`mediapackage:cloudfront_assoc` を定義する意味

`updateDistribution` を実行する際の注意点