The data lake has long been the promised land for analytics: a centralized, scalable repository for all of an organization's data. But for many, this promise soured into the reality of a "data swamp." Without the transactional guarantees and schema management of traditional databases, data lakes became slow, unreliable, and difficult to manage. Simple questions were hard to answer, and data consistency was a constant struggle.

Enter **Apache Iceberg**, an open-source table format that fundamentally solves these problems. Iceberg isn't a new query engine or storage system; it's a specification that brings database-like reliability, performance, and ease of use to the vast, low-cost storage of the data lake.

This article provides a deep dive into the architecture and game-changing features of Apache Iceberg. We'll then explore how new, purpose-built AWS services like S3 Table Buckets are making it easier than ever to deploy and manage Iceberg tables in the cloud.

---

### What is Apache Iceberg? The Table Format Revolution 📖

To understand Iceberg, it's best to use an analogy. Imagine your data files (stored as Parquet, ORC, etc., in S3) are millions of books in a massive warehouse. Older data lake technologies were like having no librarian; to find a specific piece of information, you had to wander the aisles, opening books one by one. It was slow and inefficient.

**Apache Iceberg is the master librarian and the card catalog for your data warehouse.** It's a metadata layer that sits on top of your data files, providing a fast, centralized index that tells query engines exactly which files to read to satisfy a query.

[Image of Iceberg's layered architecture]

Iceberg's architecture consists of three key layers:

1.  **The Iceberg Catalog**: This is the single entry point for any query. It's a simple key-value store (like the AWS Glue Data Catalog) that holds a pointer to the current metadata file for each table. All commits are atomic operations that update this single pointer.
2.  **The Metadata Layer**: This is the brains of Iceberg. It's a hierarchy of files (in JSON and Avro format) that track the state of a table. It includes the schema, partition configuration, and a list of "snapshots." Each snapshot represents the state of the table at a point in time and points to "manifest files" that list the actual data files.
3.  **The Data Layer**: This is the bottom layer, consisting of your actual data files in open formats like Parquet, ORC, or Avro, stored in an object store like Amazon S3. Iceberg is completely decoupled from the data format.

---

### The Four Game-Changing Features of Iceberg 🚀

This layered architecture unlocks several powerful features that were previously exclusive to traditional data warehouses.

#### 1. ACID Transactions

Iceberg brings full ACID (Atomicity, Consistency, Isolation, Durability) transactions to your data lake. A "commit" to an Iceberg table is an atomic swap of the pointer in the catalog to a new top-level metadata file. This single, simple operation means that writers don't conflict with readers, and queries always see a consistent version of the data. You can reliably perform inserts, updates, deletes, and merges without corrupting your table.

#### 2. Full Schema Evolution

With older formats like Hive, changing a table's schema was a nightmare. Renaming a column or changing its data type often required rewriting terabytes of data. Iceberg solves this by storing the schema in its metadata. Each data file is tagged with the schema version it was written with. This allows you to safely add, drop, rename, or reorder columns. New queries use the new schema, while older data can still be read correctly using its original schema, all without costly data migrations.

#### 3. Time Travel and Versioning

Every change to an Iceberg table creates a new "snapshot" of the table's state. Since old metadata and data files are not immediately deleted, Iceberg maintains a full, queryable history of the table. This is incredibly powerful:

- **Time Travel Queries**: You can run a query against the table as it existed yesterday or last week.
- **Reproducible Analytics**: Run reports or train ML models on the exact same version of the data for consistency.
- **Easy Rollbacks**: If a bad write corrupts your data, you can instantly roll back to the previous snapshot, effectively undoing the change.

#### 4. Hidden Partitioning and Performance

This is a key innovation. Older systems required you to define the physical directory structure of your table for partitioning (e.g., `/year=2025/month=09/day=14/`). This was rigid; if your query patterns changed, you had to rewrite the entire table to change the partitioning scheme.

Iceberg decouples the logical partition from the physical layout. The partition strategy is stored in the metadata, and Iceberg handles mapping it to the data files. This means you can evolve your partition scheme over time without rewriting old data. Furthermore, Iceberg collects detailed statistics on data files (like min/max values for columns), allowing query engines to perform aggressive file pruning and read only the data necessary to answer a query, dramatically improving performance.

---

### Simplifying Deployment with AWS S3 Table Buckets 🛠️

While you can run Iceberg on any standard S3 bucket, AWS has introduced **S3 Table Buckets**, a new, purpose-built bucket type designed specifically to host and manage open table formats like Iceberg.

S3 Table Buckets are a higher-level, managed service focused on **simplifying the data management lifecycle** for Iceberg tables.
The key benefits of using an S3 Table Bucket are the automated maintenance operations they provide:

- **Automated Compaction**: Automatically identifies tables with many small data files and compacts them into larger, query-optimized files in the background. This is crucial for maintaining query performance.
- **Automated Garbage Collection**: Safely identifies and deletes old, unreferenced data and metadata files from expired snapshots, helping you manage storage costs.

---

### Implementation with the AWS CDK S3 Tables Alpha Package

AWS provides a high-level CDK construct library, `@aws-cdk/aws-s3tables-alpha`, to provision this new service as code. This library allows you to define the `TableBucket`, a logical `Namespace`, and the `Table` itself, including its Iceberg properties.

Here is a conceptual example of what this looks like using TypeScript:

```typescript
import * as s3tables from '@aws-cdk/aws-s3tables-alpha'
import * as cdk from 'aws-cdk-lib'
import { Construct } from 'constructs'

export class IcebergS3TableStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props)

    // 1. Create the purpose-built S3 Table Bucket
    const analyticsBucket = new s3tables.TableBucket(this, 'AnalyticsTableBucket', {
      tableBucketName: 'my-analytics-events',
      removalPolicy: cdk.RemovalPolicy.DESTROY, // Use RETAIN for production
    })

    // 2. Create a Namespace to logically group tables
    const eventNamespace = new s3tables.Namespace(this, 'EventNamespace', {
      namespaceName: 'raw_events',
      tableBucket: analyticsBucket,
    })

    // 3. Define the Iceberg table, including its schema and managed features
    new s3tables.Table(this, 'UserEventsTable', {
      namespace: eventNamespace,
      tableName: 'user_clicks',
      openTableFormat: s3tables.OpenTableFormat.ICEBERG,
      icebergMetadata: {
        icebergSchema: {
          schemaFieldList: [
            { name: 'event_id', type: 'uuid', required: true },
            { name: 'event_timestamp', type: 'timestamptz', required: true },
            { name: 'user_id', type: 'string', required: true },
          ],
        },
      },
      // Enable the managed, automated maintenance features
      compaction: { status: s3tables.Status.ENABLED },
      snapshotManagement: { status: s3tables.Status.ENABLED },
    })
  }
}
```

This code defines a complete, production-ready setup: an S3 Table Bucket with a namespace and a schema-enforced Iceberg table, with compaction and garbage collection managed automatically by AWS.

---

### Conclusion

Apache Iceberg provides the robust, reliable, and performant foundation that data lakes have always needed. By bringing the principles of traditional databases to open object storage, it transforms a potential data swamp into a trustworthy and efficient analytics platform. With new managed services like AWS S3 Table Buckets abstracting away the operational complexities, deploying and maintaining powerful open-source data technologies has never been more accessible.


This article provides a deep dive into the architecture and game-changing features of Apache Iceberg. We'll then explore how new, purpose-built AWS services like S3 Table Buckets are making it easier than ever to deploy and manage Iceberg tables in the cloud.

large_apache-iceberg.jpg

medium_apache-iceberg.jpg

small_apache-iceberg.jpg

thumbnail_apache-iceberg.jpg

apache-iceberg.jpg

データレイクは長年、分析における約束の地とされてきた。すなわち、組織の全データを集約する、スケーラブルなリポジトリである。しかし多くの組織にとって、その約束は「データの沼」という現実に変わってしまった。従来のデータベースが持つトランザクション保証やスキーマ管理がなければ、データレイクは遅く、信頼性が低く、管理が困難になる。単純な問いに答えることさえ難しく、データの一貫性は絶え間ない闘いであった。

そこに登場したのが**Apache Iceberg**である。このオープンソースのテーブルフォーマットは、これらの問題を根本的に解決する。Iceberg は新しいクエリエンジンやストレージシステムではない。データレイクの広大で低コストなストレージに、データベースのような信頼性、パフォーマンス、そして使いやすさをもたらす仕様なのである。

この記事では、Apache Iceberg のアーキテクチャと画期的な機能について深く掘り下げる。そして、S3 テーブルバケットのような新しい専用の AWS サービスが、クラウド上での Iceberg テーブルのデプロイと管理をいかに簡単にするかを探求していく。

---

### Apache Iceberg とは何か？ テーブルフォーマット革命 📖

Iceberg を理解するには、例え話を使うのが最適だ。あなたのデータファイル（S3 に Parquet や ORC 形式で保存されている）が、巨大な倉庫にある数百万冊の本だと想像してほしい。古いデータレイク技術は、図書館員がいないようなものだった。特定の情報を見つけるには、通路をさまよい、本を一冊一冊開けてみるしかなかった。これは遅く、非効率的であった。

**Apache Iceberg は、そのデータ倉庫のマスターライブラリアンであり、図書カードカタログである。** これはデータファイルの上に位置するメタデータ層であり、クエリを満たすためにどのファイルを読み込むべきかをクエリエンジンに正確に伝える、高速で一元化されたインデックスを提供する。

Iceberg のアーキテクチャは、三つの主要な層で構成される。

1.  **Iceberg カタログ**: あらゆるクエリの唯一のエントリーポイントである。これは各テーブルの現在のメタデータファイルへのポインタを保持する単純なキーバリューストア（AWS Glue データカタログなど）だ。全てのコミットは、この単一のポインタを更新するアトミックな操作である。
2.  **メタデータ層**: Iceberg の頭脳部分である。これはテーブルの状態を追跡するファイル（JSON および Avro 形式）の階層だ。スキーマ、パーティション設定、そして「スナップショット」のリストが含まれる。各スナップショットは特定の時点でのテーブルの状態を表し、実際のデータファイルをリストアップした「マニフェストファイル」を指し示す。
3.  **データ層**: 最下層であり、Amazon S3 のようなオブジェクトストアに保存された、Parquet、ORC、Avro といったオープンフォーマットの実際のデータファイルで構成される。Iceberg はデータフォーマットから完全に分離されている。

---

### Iceberg の 4 つの画期的な特徴 🚀

この階層化されたアーキテクチャは、以前は従来のデータウェアハウスにしかなかった、いくつかの強力な機能を解き放つ。

#### 1. ACID トランザクション

Iceberg は、データレイクに完全な ACID（原子性、一貫性、分離性、耐久性）トランザクションをもたらす。Iceberg テーブルへの「コミット」は、カタログ内のポインタを新しいトップレベルのメタデータファイルへとアトミックに交換する操作である。この単一でシンプルな操作により、書き込み処理が読み取り処理と衝突せず、クエリは常に一貫したバージョンのデータを参照できる。テーブルを破損させることなく、挿入、更新、削除、マージを確実に行うことができる。

#### 2. 完全なスキーマ進化

Hive のような古いフォーマットでは、テーブルのスキーマ変更は悪夢だった。列の名前変更やデータ型の変更は、しばしばテラバイト級のデータの再書き込みを必要とした。Iceberg は、スキーマをメタデータに保存することでこの問題を解決する。各データファイルには、それが書き込まれた際のスキーマバージョンがタグ付けされる。これにより、列を安全に追加、削除、名前変更、または並べ替えることができる。新しいクエリは新しいスキーマを使い、古いデータはその元のスキーマを使って正しく読み取ることができる。これら全てが、コストのかかるデータ移行なしに可能となる。

#### 3. タイムトラベルとバージョニング

Iceberg テーブルへの全ての変更は、テーブルの状態の新しい「スナップショット」を作成する。古いメタデータとデータファイルはすぐには削除されないため、Iceberg はテーブルの完全でクエリ可能な履歴を維持する。これは非常に強力だ。

- **タイムトラベルクエリ**: 昨日や先週の時点でのテーブルに対してクエリを実行できる。
- **再現可能な分析**: 一貫性を保つため、全く同じバージョンのデータに対してレポートを実行したり、ML モデルをトレーニングしたりできる。
- **簡単なロールバック**: 不正な書き込みでデータが破損した場合、即座に前のスナップショットにロールバックし、変更を効果的に元に戻すことができる。

#### 4. 隠れパーティショニングとパフォーマンス

これは重要な革新点である。古いシステムでは、パーティショニングのためにテーブルの物理的なディレクトリ構造を定義する必要があった（例：`/year=2025/month=09/day=14/`）。これは硬直的で、クエリのパターンが変わった場合、パーティショニングスキームを変更するためにテーブル全体を再書き込みする必要があった。

Iceberg は論理的なパーティションを物理的なレイアウトから切り離す。パーティション戦略はメタデータに保存され、Iceberg がそれをデータファイルにマッピングする。これにより、古いデータを書き換えることなく、時間と共にパーティションスキームを進化させることができる。さらに、Iceberg はデータファイルに関する詳細な統計情報（列の最小/最大値など）を収集し、クエリエンジンが積極的なファイルプルーニング（不要ファイルの除外）を行い、クエリに必要なデータのみを読み取ることを可能にし、パフォーマンスを劇的に向上させる。

---

### AWS S3 テーブルバケットによるデプロイの簡素化 🛠️

Iceberg は標準の S3 バケット上でも実行可能だが、AWS は**S3 テーブルバケット**を導入した。これは、Iceberg のようなオープンテーブルフォーマットをホストし、管理するために特別に設計された、新しい専用のバケットタイプである。
S3 テーブルバケットは、Iceberg テーブルの**データ管理ライフサイクルを簡素化する**ことに焦点を当てた、より高レベルのマネージドサービスである。

S3 テーブルバケットを使用する主な利点は、それが提供する自動化されたメンテナンス操作にある。

- **自動コンパクション**: 多数の小さなデータファイルを持つテーブルを自動的に特定し、バックグラウンドでより大きな、クエリに最適化されたファイルに結合する。これはクエリのパフォーマンスを維持するために不可欠だ。
- **自動ガベージコレクション**: 期限切れのスナップショットから古くて参照されなくなったデータファイルやメタデータファイルを安全に特定し削除することで、ストレージコストの管理を支援する。

---

### AWS CDK S3 Tables Alpha パッケージによる実装

AWS は、この新しいサービスをコードとしてプロビジョニングするための高レベル CDK コンストラクトライブラリ`@aws-cdk/aws-s3tables-alpha`を提供している。このライブラリにより、`TableBucket`、論理的な`Namespace`、そして`Table`自体を、その Iceberg プロパティを含めて定義できる。

TypeScript を使用した概念的な例を以下に示す。

```typescript
import * as s3tables from '@aws-cdk/aws-s3tables-alpha'
import * as cdk from 'aws-cdk-lib'
import { Construct } from 'constructs'

export class IcebergS3TableStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props)

    // 1. 専用のS3テーブルバケットを作成する
    const analyticsBucket = new s3tables.TableBucket(this, 'AnalyticsTableBucket', {
      tableBucketName: 'my-analytics-events',
      removalPolicy: cdk.RemovalPolicy.DESTROY, // 本番環境ではRETAINを使用
    })

    // 2. テーブルを論理的にグループ化するための名前空間を作成する
    const eventNamespace = new s3tables.Namespace(this, 'EventNamespace', {
      namespaceName: 'raw_events',
      tableBucket: analyticsBucket,
    })

    // 3. Icebergテーブル自体を、スキーマや管理機能を含めて定義する
    new s3tables.Table(this, 'UserEventsTable', {
      namespace: eventNamespace,
      tableName: 'user_clicks',
      openTableFormat: s3tables.OpenTableFormat.ICEBERG,
      icebergMetadata: {
        icebergSchema: {
          schemaFieldList: [
            { name: 'event_id', type: 'uuid', required: true },
            { name: 'event_timestamp', type: 'timestamptz', required: true },
            { name: 'user_id', type: 'string', required: true },
          ],
        },
      },
      // マネージドの自動メンテナンス機能を有効化する
      compaction: { status: s3tables.Status.ENABLED },
      snapshotManagement: { status: s3tables.Status.ENABLED },
    })
  }
}
```

このコードは、本番環境に対応可能な完全なセットアップを定義している。すなわち、名前空間を持つ S3 テーブルバケットと、スキーマが適用された Iceberg テーブルであり、コンパクションとガベージコレクションは AWS によって自動的に管理される。

---

### 結論

Apache Iceberg は、データレイクが常に必要としてきた、堅牢で信頼性が高く、高性能な基盤を提供する。従来のデータベースの原則をオープンなオブジェクトストレージにもたらすことで、潜在的なデータの沼を、信頼できる効率的な分析プラットフォームへと変貌させる。AWS S3 テーブルバケットのような新しいマネージドサービスが運用上の複雑さを抽象化することで、強力なオープンソースデータ技術のデプロイと維持は、これまで以上にアクセスしやすくなっている。


Apache Iceberg のアーキテクチャと画期的な機能について深く掘り下げる。そして、S3 テーブルバケットのような新しい専用の AWS サービスが、クラウド上での Iceberg テーブルのデプロイと管理をいかに簡単にするかを探求していく。

モダンデータレイクの基盤：Apache Iceberg への深掘り

The Modern Data Lake Foundation: A Deep Dive into Apache Iceberg

Marko Leinikka

In the modern digital landscape, the line between a website and an application is blurring. Users expect fast, reliable, and engaging experiences regardless of their device or network condition. For years, native applications were the gold standard for achieving this, but they came with the cost of platform-specific development and the friction of app store distribution. The web, on the other hand, offered unparalleled reach but often struggled with performance and offline capabilities.

Progressive Web Apps (PWAs) have emerged as the solution to this dilemma. A PWA is not a new framework or technology but a development paradigm that uses modern web capabilities to deliver an app-like experience directly in the browser. They represent a fusion of the web's accessibility with the rich functionality of native apps. This article explores the core principles of PWAs, the technologies that power them, the significant benefits they offer, and how you can start building one with a modern stack like Next.js and Serwist.

---

### The Three Pillars of a PWA

To be considered a PWA, a web application must embody three key characteristics. These pillars ensure the application feels robust and trustworthy, just like a native app.

#### 1. Reliable 📶

A PWA must be reliable, meaning it loads instantly and works consistently, even in uncertain network conditions. The core technology that enables this is the **Service Worker**. A Service Worker acts as a client-side proxy, intercepting network requests from your application. This allows developers to implement sophisticated caching strategies, pre-caching key resources (the "App Shell") so that the user interface loads instantly on repeat visits. More importantly, it allows the app to function offline, serving cached content when the network is unavailable instead of showing the browser's dreaded "No Internet" page.

#### 2. Fast ⚡

Performance is not a feature; it's a foundation. PWAs are designed to be fast, providing smooth animations, quick responses to user interaction, and a seamless overall experience. This speed is a direct result of the service worker's caching capabilities. By caching the App Shell—the minimal HTML, CSS, and JavaScript required to power the UI—the app can load the basic structure from the local cache almost instantly. It then populates the dynamic content, often from the network, but the user perceives the application as being immediately available. This focus on performance is critical for user retention, as studies consistently show that users abandon slow-loading sites.

#### 3. Engaging 📱

Finally, a PWA must be engaging. It should feel like a first-class citizen on the user's device. This is achieved through several key features:

- **Installable:** PWAs can be "installed" on a user's home screen or app drawer with a single tap, without needing an app store. This is enabled by the **Web App Manifest** file.
- **App-like Experience:** When launched from the home screen, a PWA can run in its own standalone window, without the browser's address bar or UI, providing an immersive, full-screen experience.
- **Push Notifications:** Using Service Workers, PWAs can receive and display push notifications even when the browser is closed, allowing businesses to re-engage users with timely and relevant updates.

---

### Core Technologies Under the Hood

Two key technologies form the backbone of every PWA.

#### Web App Manifest

The **Web App Manifest** is a simple JSON file that gives you control over how your app appears to the user when installed. It provides essential metadata, including:

- `name` and `short_name`: The name of the application displayed on the home screen.
- `icons`: A set of icons for the home screen, splash screen, etc., in various resolutions.
- `start_url`: The URL that is loaded when the PWA is launched.
- `display`: Defines the display mode, such as `standalone` for a native feel or `fullscreen`.
- `background_color` and `theme_color`: Used for the splash screen and theming the browser UI.

A simple manifest might look like this:

```json
{
  "name": "My Awesome PWA",
  "short_name": "AwesomePWA",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#FFFFFF",
  "theme_color": "#3367D6",
  "icons": [
    {
      "src": "/icons/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "/icons/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}
```

#### Service Workers

As mentioned, the Service Worker is the workhorse of a PWA. It's a script that the browser runs in the background, separate from the web page, and is the key to enabling features like offline support, background sync, and push notifications. The service worker has a distinct lifecycle (Registration, Installation, Activation) that allows it to take control of pages and manage events without blocking the main browser thread. Its ability to intercept and handle network requests (`fetch` events) is what makes sophisticated caching and offline strategies possible.

It's also important to note that PWAs **must be served over HTTPS**. This is a security requirement because Service Workers can intercept and modify requests, making them a potential target for man-in-the-middle attacks on an insecure connection.

---

### Getting Started with Next.js and Serwist

Building a PWA from scratch can be complex, especially managing the Service Worker lifecycle and caching strategies. Fortunately, modern tools abstract away much of this complexity. For developers using Next.js, **Serwist** is an excellent choice. It's a collection of libraries that brings the power of Workbox (a popular Google library for service workers) into the Next.js ecosystem.

With Serwist, you don't need to write a service worker by hand. Instead, you configure it in your Next.js project, and it will automatically generate a highly optimized service worker for you. This generated script will handle precaching your static assets, defining runtime caching strategies for dynamic content, and more.

The setup is straightforward. First, you install the necessary packages:

```bash
npm install @serwist/next
```

Then, you wrap your Next.js configuration with the Serwist wrapper. This tells Serwist to inject the PWA logic into your build process.

```typescript
// next.config.mjs
import { withSerwist } from '@serwist/next'

/** @type {import('next').NextConfig} */
const nextConfig = {
  // Your Next.js config
}

export default withSerwist({
  // Your Serwist config
  swSrc: 'app/sw.ts',
  swDest: 'public/sw.js',
})(nextConfig)
```

You would also create your manifest file in the `public` directory and link to it in your main layout file (`app/layout.tsx`). With just this minimal setup, Serwist handles the heavy lifting of precaching your pages and assets, instantly giving your Next.js application the "Reliable" and "Fast" pillars of a PWA.

---

### Conclusion

Progressive Web Apps represent a significant evolution in web development. They bridge the gap between web and native, offering a powerful way to deliver fast, reliable, and engaging experiences without the hurdles of app stores. By leveraging core technologies like Service Workers and the Web App Manifest, developers can create applications that are discoverable by search engines, work offline, and live on the user's home screen. With modern toolchains like Next.js and Serwist simplifying the implementation, there has never been a better time to consider a PWA for your next project.


This article explores the core principles of PWAs, the technologies that power them, the significant benefits they offer, and how you can start building one with a modern stack like Next.js and Serwist.

large_pwa.png

medium_pwa.png

small_pwa.png

thumbnail_pwa.png

pwa.png

現代のデジタル環境において、ウェブサイトとアプリケーションの境界線は曖昧になりつつある。ユーザーは、デバイスやネットワークの状態に関わらず、高速で信頼性が高く、魅力的な体験を期待している。長年、ネイティブアプリケーションがこれを実現する最良の手段であったが、それにはプラットフォーム固有の開発コストやアプリストアという配布の障壁が伴った。一方、ウェブは比類なきリーチを誇るものの、パフォーマンスやオフライン機能の面でしばしば課題を抱えていた。

プログレッシブウェブアプリ（PWA）は、このジレンマに対する解決策として登場した。PWA は新しいフレームワークや技術ではなく、最新のウェブ機能を活用してアプリのような体験をブラウザ内で直接提供する開発パラダイムである。PWA は、ウェブのアクセシビリティとネイティブアプリの豊富な機能性を融合させたものだ。この記事では、PWA の基本原則、それを支える技術、PWA が提供する大きな利点、そして Next.js や Serwist といった最新のスタックで PWA を構築し始める方法について探求する。

---

### PWA を構成する三つの柱

ウェブアプリケーションが PWA と見なされるためには、三つの主要な特性を具体化する必要がある。これらの柱は、アプリケーションがネイティブアプリのように堅牢で信頼できるものであることを保証する。

#### 1. 信頼性 (Reliable) 📶

PWA は信頼性が高くなければならない。これは、不安定なネットワーク環境下であっても即座に読み込まれ、安定して動作することを意味する。これを可能にする中心技術が**サービスワーカー**である。サービスワーカーはクライアントサイドのプロキシとして機能し、アプリケーションからのネットワークリクエストを横取りする。これにより、開発者は高度なキャッシング戦略を実装でき、主要なリソース（「App Shell」）を事前にキャッシュすることで、再訪問時にユーザーインターフェースが瞬時に表示されるようになる。さらに重要なのは、ネットワークが利用できない場合でも、ブラウザの絶望的な「インターネットに接続されていません」ページを表示する代わりに、キャッシュされたコンテンツを提供してアプリがオフラインで機能できるようにすることだ。

#### 2. 高速性 (Fast) ⚡

パフォーマンスは単なる機能ではなく、土台である。PWA は高速であるように設計されており、スムーズなアニメーション、ユーザー操作への素早い応答、そしてシームレスな全体験を提供する。この速度は、サービスワーカーのキャッシング能力の直接的な結果である。UI を動かすために必要な最小限の HTML、CSS、JavaScript である App Shell をキャッシュすることで、アプリは基本的な構造をローカルキャッシュからほぼ瞬時に読み込むことができる。その後、動的なコンテンツをネットワークから読み込むが、ユーザーはアプリケーションがすぐに利用可能であると認識する。ユーザーの離脱を防ぐ上で、このパフォーマンスへの注力は極めて重要である。

#### 3. エンゲージメント (Engaging) 📱

最後に、PWA はエンゲージメントが高くなければならない。ユーザーのデバイス上で第一級の存在であるかのように感じさせる必要がある。これはいくつかの主要な機能によって達成される。

- **インストール可能:** PWA はアプリストアを介さず、ワンタップでユーザーのホーム画面やアプリドロワーに「インストール」できる。これは**ウェブアプリマニフェスト**ファイルによって可能になる。
- **アプリのような体験:** ホーム画面から起動すると、PWA はブラウザのアドレスバーや UI なしで独自のスタンドアロンウィンドウで実行でき、没入感のあるフルスクリーン体験を提供する。
- **プッシュ通知:** サービスワーカーを使用することで、PWA はブラウザが閉じていてもプッシュ通知を受信・表示できる。これにより、企業はタイムリーで関連性の高い更新情報でユーザーと再エンゲージメントを図ることができる。

---

### PWA を支えるコア技術

すべての PWA のバックボーンを形成するのは、二つの主要な技術である。

#### ウェブアプリマニフェスト

**ウェブアプリマニフェスト**は、インストールされたアプリがユーザーにどのように表示されるかを制御するためのシンプルな JSON ファイルである。これには、以下のような必須のメタデータが含まれる。

- `name`, `short_name`: ホーム画面に表示されるアプリケーション名。
- `icons`: ホーム画面やスプラッシュスクリーンなどで使用される、様々な解像度のアイコンセット。
- `start_url`: PWA 起動時に読み込まれる URL。
- `display`: `standalone`（ネイティブ風）や `fullscreen` などの表示モードを定義。
- `background_color`, `theme_color`: スプラッシュスクリーンやブラウザ UI のテーマ設定に使用。

簡単なマニフェストは次のようになる。

```json
{
  "name": "すごいPWA",
  "short_name": "すごいPWA",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#FFFFFF",
  "theme_color": "#3367D6",
  "icons": [
    {
      "src": "/icons/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "/icons/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}
```

#### サービスワーカー

前述の通り、サービスワーカーは PWA の原動力だ。これはブラウザがウェブページとは別にバックグラウンドで実行するスクリプトであり、オフラインサポート、バックグラウンド同期、プッシュ通知といった機能を可能にする鍵である。サービスワーカーには明確なライフサイクル（登録、インストール、アクティベート）があり、メインのブラウザスレッドをブロックすることなくページを制御し、イベントを管理することができる。ネットワークリクエスト（`fetch`イベント）を捕捉して処理する能力こそが、高度なキャッシングやオフライン戦略を可能にする。

また、PWA は**HTTPS 経由で提供されなければならない**点も重要だ。これはセキュリティ上の要件であり、サービスワーカーはリクエストを傍受・変更できるため、安全でない接続上では中間者攻撃の標的になる可能性があるからだ。

---

### Next.js と Serwist で始める PWA 開発

PWA をゼロから構築するのは、特にサービスワーカーのライフサイクルやキャッシング戦略の管理において複雑になりがちだ。幸いなことに、現代のツールはこの複雑さの多くを抽象化してくれる。Next.js を使用する開発者にとって、**Serwist**は優れた選択肢である。これは、Workbox（サービスワーカー用の人気 Google ライブラリ）のパワーを Next.js エコシステムにもたらすライブラリ群だ。

Serwist を使えば、サービスワーカーを手書きする必要はない。代わりに Next.js プロジェクトで設定を行うだけで、高度に最適化されたサービスワーカーが自動的に生成される。この生成されたスクリプトは、静的アセットのプレキャッシング、動的コンテンツのランタイムキャッシング戦略の定義などを処理してくれる。

セットアップは簡単だ。まず、必要なパッケージをインストールする。

```bash
npm install @serwist/next
```

次に、Next.js の設定を Serwist のラッパーで囲む。これにより、Serwist はビルドプロセスに PWA ロジックを注入する。

```typescript
// next.config.mjs
import { withSerwist } from '@serwist/next'

/** @type {import('next').NextConfig} */
const nextConfig = {
  // Next.jsの設定
}

export default withSerwist({
  // Serwistの設定
  swSrc: 'app/sw.ts',
  swDest: 'public/sw.js',
})(nextConfig)
```

また、`public`ディレクトリにマニフェストファイルを作成し、メインのレイアウトファイル（`app/layout.tsx`）からリンクする。この最小限の設定だけで、Serwist がページやアセットのプレキャッシングといった重労働を担い、Next.js アプリケーションに PWA の「信頼性」と「高速性」の柱を即座にもたらす。

---

### 結論

プログレッシブウェブアプリは、ウェブ開発における重要な進化を象徴している。ウェブとネイティブの間のギャップを埋め、アプリストアの障壁なしに高速で信頼性が高く、魅力的な体験を提供する強力な手段となる。サービスワーカーやウェブアプリマニフェストのようなコア技術を活用することで、開発者は検索エンジンに発見され、オフラインで動作し、ユーザーのホーム画面に常駐するアプリケーションを作成できる。Next.js や Serwist のような現代のツールチェーンが実装を簡素化している今、次のプロジェクトで PWA を検討するのにこれほど良い時期はないだろう。


PWA の基本原則、それを支える技術、PWA が提供する大きな利点、そして Next.js や Serwist といった最新のスタックで PWA を構築し始める方法について探求する。

ブラウザを超えて：プログレッシブウェブアプリ（PWA）入門

Beyond the Browser: An Introduction to Progressive Web Apps (PWAs)

For decades, the dominant approach to persisting data has been state-oriented. We create, read, update, and delete (CRUD) records in a database. When a user's details change, we run an `UPDATE` statement, overwriting the old data. This approach is simple and well-understood, but it has a fundamental drawback: **it erases history**. We know the _current_ state of our data, but we lose the rich context and intent behind _how_ it got there. Why was this order's status changed to "returned"? When was this product's price last adjusted? Answering these questions with a state-oriented model is often difficult or impossible.

**Event Sourcing** offers a powerful alternative. Instead of storing just the current state, we store the full sequence of immutable events that have ever occurred. The state of our application becomes a derivative of this event history. Think of it like a bank account: a traditional database might only store your current balance ($150), but an event-sourced system stores the entire transaction ledger (+$200 deposit, -$50 withdrawal). You can always calculate the current balance from the ledger, but you can never reconstruct the ledger from just the balance.

This article explores the principles of Event Sourcing, its significant advantages for complex domains, and how to implement the core concepts in Go.

---

### What is Event Sourcing? 📖

Event Sourcing is an architectural pattern where the single source of truth is a log of domain events. An "event" is a record of something that happened in the business domain. The state of an entity, called an **Aggregate**, is derived by replaying these events in order.

#### Core Components:

- **Events**: These are immutable facts about the past, named in the past tense. For example, `OrderPlaced`, `ItemAddedToCart`, or `PaymentProcessed`. They contain all the necessary data to understand what happened.
- **Commands**: A command is a request to perform an action. For example, `PlaceOrder` or `AddItemToCart`. A command is processed by an Aggregate and may result in one or more events being generated, or it may be rejected.
- **Aggregate**: An Aggregate is a consistency boundary that processes commands and produces events. It's a business object (like an `Order` or `ShoppingCart`) that encapsulates state and enforces business rules. Its state is never persisted directly; it's always rebuilt from its history of events.
- **Event Store**: This is the database that stores the events. It's an append-only log, optimized for writing new events and reading the full stream of events for a specific aggregate.

The typical flow is:
`Client` -> `Command` -> `Aggregate` -> `Event(s)` -> `Event Store`

---

### The Benefits of Thinking in Events 📈

Adopting Event Sourcing is a paradigm shift, but it unlocks several powerful capabilities that are difficult to achieve with traditional CRUD systems.

#### 1. Complete Audit Trail

Since every state change is recorded as an immutable event, you have a perfect, unchangeable log of everything that has ever happened in the system. This is invaluable for debugging ("What series of actions led to this bug?"), auditing ("Show me all changes related to this user"), and business intelligence ("What is the most common time for cart abandonment?").

#### 2. Temporal Queries & Time Travel

Because the state is a derivative of the event log, you can reconstruct the state of any aggregate at _any point in time_. You simply stop replaying events at a specific timestamp or event number. This "time travel" ability is incredibly powerful for historical analysis and understanding how your data has evolved.

#### 3. Decoupling and Projections (CQRS)

This is arguably the most significant benefit. The event stream is the source of truth for writes, but it's not always the most efficient format for reads. With Event Sourcing, you can create multiple, highly-optimized **read models** (or **Projections**) by listening to the stream of events.
For example, a single `OrderPlaced` event could be used to:

- Update a relational database table that backs the customer's order history page.
- Update a search index like Elasticsearch to make the order searchable.
- Feed data into a reporting dashboard.

This separation of read and write models is the core idea behind **Command Query Responsibility Segregation (CQRS)**, a pattern that pairs naturally with Event Sourcing.

---

### A Practical Example in Go

Let's model a simple shopping cart to see how these concepts translate into Go code. We won't build a full event store, but we'll focus on the aggregate and event logic.

#### 1. Define the Events

First, we define our events as structs. We'll use an interface to handle them polymorphically.

```go
package main

// Event is the interface for all domain events.
type Event interface {
    isEvent() // Marker method
}

// ItemAdded represents the event when an item is added to the cart.
type ItemAdded struct {
    ItemID   string
    Price    float64
    Quantity int
}

func (e ItemAdded) isEvent() {}

// CartCheckedOut represents the event when the cart is finalized.
type CartCheckedOut struct {
    CheckoutID string
}

func (e CartCheckedOut) isEvent() {}
```

#### 2. Define the Aggregate

The `ShoppingCart` aggregate holds the state, which is built by applying events. Notice it doesn't export its fields; state changes are controlled internally.

```go
package main

import "fmt"

// ShoppingCart is our aggregate.
type ShoppingCart struct {
    ID        string
    items     map[string]int
    totalCost float64
    checkedOut bool
}

// NewShoppingCart creates an empty cart.
func NewShoppingCart(id string) *ShoppingCart {
    return &ShoppingCart{
        ID:    id,
        items: make(map[string]int),
    }
}

// HandleCommand processes a command and returns the resulting event.
// In a real app, this would be split into multiple methods like AddItem, Checkout etc.
func (c *ShoppingCart) AddItem(itemID string, price float64, quantity int) (Event, error) {
    if c.checkedOut {
        return nil, fmt.Errorf("cannot add items to a checked-out cart")
    }
    if quantity <= 0 {
        return nil, fmt.Errorf("quantity must be positive")
    }

    // Command is valid, produce an event
    return ItemAdded{ItemID: itemID, Price: price, Quantity: quantity}, nil
}

// Apply modifies the aggregate's state based on an event.
// THIS IS THE ONLY PLACE STATE SHOULD BE MUTATED.
func (c *ShoppingCart) Apply(event Event) {
    switch e := event.(type) {
    case ItemAdded:
        c.items[e.ItemID] += e.Quantity
        c.totalCost += e.Price * float64(e.Quantity)
    case CartCheckedOut:
        c.checkedOut = true
    }
}
```

#### 3. Rehydrating the Aggregate

To get the current state of a cart, we don't fetch it from a database row. We fetch its event history and replay them. This process is called **rehydration**.

```go
package main

// RehydrateShoppingCart rebuilds the state of a cart from its event history.
func RehydrateShoppingCart(id string, events []Event) *ShoppingCart {
    cart := NewShoppingCart(id)
    for _, event := range events {
        cart.Apply(event)
    }
    return cart
}

// --- Conceptual Event Store ---
// type EventStore interface {
//     GetEvents(aggregateID string) []Event
//     SaveEvents(aggregateID string, events []Event) error
// }
```

In a real application, a command handler would first `Rehydrate` the aggregate, then call a command method (`AddItem`), and if an event is produced, save it to the `EventStore`.

---

### Challenges and Considerations 🤔

Event Sourcing is not a silver bullet. It introduces its own set of challenges:

- **Learning Curve**: It requires a shift in mindset away from the familiar CRUD model.
- **Eventual Consistency**: Because read models (projections) are often updated asynchronously, the system becomes eventually consistent, which can impact user experience if not handled carefully.
- **Event Versioning**: Over time, the structure of your events may need to change. This requires a strategy for versioning and migrating events, such as upcasting (transforming old events to a new format on the fly).

---

### Conclusion

Event Sourcing is a powerful architectural pattern that provides a complete historical record of your data, enables robust auditing and temporal analysis, and fosters highly decoupled and scalable systems through projections. While it introduces complexity, for applications with complex business logic and a need for a strong audit trail, it offers a fundamentally more robust and flexible way to model and persist data. By thinking in events instead of state, you can build systems that not only know what their data _is_, but also _how it came to be_.


This article explores the principles of Event Sourcing, its significant advantages for complex domains, and how to implement the core concepts in Go.

large_event-sourcing-image.webp

medium_event-sourcing-image.webp

small_event-sourcing-image.webp

thumbnail_event-sourcing-image.webp

event-sourcing-image.webp

数十年にわたり、データを永続化する主要なアプローチは状態指向であった。我々はデータベース内のレコードを作成、読み取り、更新、削除（CRUD）する。ユーザーの詳細が変更されれば、`UPDATE`文を実行して古いデータを上書きする。このアプローチはシンプルでよく理解されているが、根本的な欠点がある。それは**歴史を消去してしまう**ことだ。データの*現在*の状態はわかるが、そこに至るまでの背景や意図といった豊かな文脈は失われる。「なぜこの注文のステータスが『返品済み』に変更されたのか？」「この製品の価格が最後に調整されたのはいつか？」こうした問いに状態指向モデルで答えるのは、しばしば困難か、あるいは不可能である。

**イベントソーシング**は、強力な代替案を提示する。現在の状態だけを保存するのではなく、これまでに発生した不変のイベントの完全なシーケンスを保存するのだ。アプリケーションの状態は、このイベント履歴から派生したものとなる。銀行口座で考えてみるとわかりやすい。従来のデータベースは現在の残高（例：150 ドル）のみを保存するかもしれないが、イベントソーシングのシステムは取引の全台帳（+200 ドルの入金、-50 ドルの出金）を保存する。台帳から現在の残高を計算することは常に可能だが、残高だけから台帳を再構築することは決してできない。

この記事では、イベントソーシングの原則、複雑なドメインにおけるその大きな利点、そして Go でその中心的な概念を実装する方法を探求する。

---

### イベントソーシングとは何か 📖

イベントソーシングとは、ビジネスドメインで発生したイベントのログを唯一の信頼できる情報源（Single Source of Truth）とするアーキテクチャパターンである。「イベント」とは、ビジネスドメインで起こった出来事の記録を指す。**アグリゲート**と呼ばれるエンティティの状態は、これらのイベントを順番に再生することによって導き出される。

#### 主要な構成要素：

- **イベント (Events)**: 過去に起こった不変の事実であり、過去形で命名される。例：`OrderPlaced`（注文が行われた）、`ItemAddedToCart`（アイテムがカートに追加された）、`PaymentProcessed`（支払いが処理された）。イベントには、何が起こったかを理解するために必要な全てのデータが含まれる。
- **コマンド (Commands)**: アクションの実行を要求するもの。例：`PlaceOrder`、`AddItemToCart`。コマンドはアグリゲートによって処理され、一つ以上のイベントが生成されるか、あるいは拒否されることがある。
- **アグリゲート (Aggregate)**: コマンドを処理し、イベントを生成する一貫性の境界。状態をカプセル化し、ビジネスルールを強制するビジネスオブジェクト（`Order`や`ShoppingCart`など）。その状態は直接永続化されず、常にイベントの履歴から再構築される。
- **イベントストア (Event Store)**: イベントを保存するデータベース。追記専用のログであり、新しいイベントの書き込みと特定のアグリゲートの全イベントストリームの読み取りに最適化されている。

典型的なフローは以下の通りだ。
`クライアント` -> `コマンド` -> `アグリゲート` -> `イベント群` -> `イベントストア`

---

### イベントで考えることの利点 📈

イベントソーシングを採用することはパラダイムシフトを伴うが、従来の CRUD システムでは達成が困難な、いくつかの強力な能力を解き放つ。

#### 1. 完全な監査証跡

全ての状態変更が不変のイベントとして記録されるため、システムでこれまでに起こった全ての出来事に関する完璧で変更不可能なログが手に入る。これはデバッグ（「どの様な一連のアクションがこのバグを引き起こしたか？」）、監査（「このユーザーに関連する全ての変更を表示せよ」）、ビジネスインテリジェンス（「カート放棄が最も多い時間帯はいつか？」）にとって計り知れない価値がある。

#### 2. 時間的クエリとタイムトラベル

状態はイベントログの派生物であるため、*任意の時点*における任意のアグリゲートの状態を再構築できる。特定のタイムスタンプやイベント番号でイベントの再生を停止するだけだ。この「タイムトラベル」能力は、履歴分析やデータがどのように変化してきたかを理解する上で非常に強力である。

#### 3. 分離とプロジェクション (CQRS)

これは間違いなく最大の利点だろう。イベントストリームは書き込みの信頼できる情報源だが、読み取りには必ずしも最も効率的な形式ではない。イベントソーシングでは、イベントストリームをリッスンすることで、複数の高度に最適化された**リードモデル**（または**プロジェクション**）を作成できる。
例えば、単一の`OrderPlaced`イベントは、以下の目的で使用されうる。

- 顧客の注文履歴ページを支えるリレーショナルデータベースのテーブルを更新する。
- 注文を検索可能にするために Elasticsearch のような検索インデックスを更新する。
- レポート用ダッシュボードにデータを供給する。

このように読み書きのモデルを分離する考え方は、**コマンド・クエリ責務分離（CQRS）**の核となるアイデアであり、イベントソーシングと自然に組み合わさるパターンである。

---

### Go による実践的な例

これらの概念が Go のコードでどのように表現されるかを見るために、簡単なショッピングカートをモデル化してみよう。完全なイベントストアは構築しないが、アグリゲートとイベントのロジックに焦点を当てる。

#### 1. イベントの定義

まず、イベントを構造体として定義する。多態的に扱うためにインターフェースを使用する。

```go
package main

// Eventは全てのドメインイベントのインターフェースである。
type Event interface {
    isEvent() // マーカーメソッド
}

// ItemAddedはアイテムがカートに追加された時のイベントを表す。
type ItemAdded struct {
    ItemID   string
    Price    float64
    Quantity int
}

func (e ItemAdded) isEvent() {}

// CartCheckedOutはカートが精算された時のイベントを表す。
type CartCheckedOut struct {
    CheckoutID string
}

func (e CartCheckedOut) isEvent() {}
```

#### 2. アグリゲートの定義

`ShoppingCart`アグリゲートは状態を保持し、その状態はイベントを適用することで構築される。フィールドがエクスポートされていない点に注目してほしい。状態変更は内部で制御される。

```go
package main

import "fmt"

// ShoppingCartは我々のアグリゲートである。
type ShoppingCart struct {
    ID        string
    items     map[string]int
    totalCost float64
    checkedOut bool
}

// NewShoppingCartは空のカートを作成する。
func NewShoppingCart(id string) *ShoppingCart {
    return &ShoppingCart{
        ID:    id,
        items: make(map[string]int),
    }
}

// AddItemはコマンドを処理し、結果のイベントを返す。
// 実際のアプリでは、AddItemやCheckoutなどの複数のメソッドに分割されるだろう。
func (c *ShoppingCart) AddItem(itemID string, price float64, quantity int) (Event, error) {
    if c.checkedOut {
        return nil, fmt.Errorf("精算済みのカートにアイテムは追加できない")
    }
    if quantity <= 0 {
        return nil, fmt.Errorf("数量は正でなければならない")
    }

    // コマンドは有効なので、イベントを生成する
    return ItemAdded{ItemID: itemID, Price: price, Quantity: quantity}, nil
}

// Applyはイベントに基づいてアグリゲートの状態を変更する。
// 状態が変更されるべき唯一の場所がここである。
func (c *ShoppingCart) Apply(event Event) {
    switch e := event.(type) {
    case ItemAdded:
        c.items[e.ItemID] += e.Quantity
        c.totalCost += e.Price * float64(e..Quantity)
    case CartCheckedOut:
        c.checkedOut = true
    }
}
```

#### 3. アグリゲートの再水和（Rehydration）

カートの現在の状態を取得するために、データベースの行からフェッチするのではない。イベント履歴を取得し、それらを再生する。このプロセスは**再水和（Rehydration）**と呼ばれる。

```go
package main

// RehydrateShoppingCartはイベント履歴からカートの状態を再構築する。
func RehydrateShoppingCart(id string, events []Event) *ShoppingCart {
    cart := NewShoppingCart(id)
    for _, event := range events {
        cart.Apply(event)
    }
    return cart
}

// --- 概念的なイベントストア ---
// type EventStore interface {
//     GetEvents(aggregateID string) []Event
//     SaveEvents(aggregateID string, events []Event) error
// }
```

実際のアプリケーションでは、コマンドハンドラはまずアグリゲートを`Rehydrate`し、次にコマンドメソッド（`AddItem`）を呼び出し、イベントが生成されればそれを`EventStore`に保存する。

---

### 課題と考慮事項 🤔

イベントソーシングは万能薬ではない。それ自体が持つ課題も存在する。

- **学習曲線**: 使い慣れた CRUD モデルからの思考の転換が必要である。
- **結果整合性**: リードモデル（プロジェクション）は非同期に更新されることが多いため、システムは結果整合性を持つことになる。これを慎重に扱わないとユーザー体験に影響を与える可能性がある。
- **イベントのバージョニング**: 時間の経過とともに、イベントの構造を変更する必要が出てくるかもしれない。これには、アップキャスティング（古いイベントを新しい形式にその場で変換する）など、イベントのバージョニングとマイグレーションのための戦略が必要となる。

---

### 結論

イベントソーシングは、データの完全な履歴記録を提供し、堅牢な監査と時間的分析を可能にし、プロジェクションを通じて高度に分離されスケーラブルなシステムを促進する強力なアーキテクチャパターンである。複雑さを伴うものの、複雑なビジネスロジックと強力な監査証跡を必要とするアプリケーションにとっては、データをモデル化し永続化するための、より根本的に堅牢で柔軟な方法を提供する。状態ではなくイベントで考えることにより、データが*何であるか*だけでなく、*それがどのようにしてそうなったか*を知るシステムを構築できるのだ。


イベントソーシングの原則、複雑なドメインにおけるその大きな利点、そして Go でその中心的な概念を実装する方法を探求する。

状態を超えて：Go によるイベントソーシング実践入門

Beyond State: A Practical Introduction to Event Sourcing in Go

Building a modern web application often feels like an exercise in assembling a complex puzzle. You need a database, an ORM, an API framework, an authentication system, a file storage solution, and an admin panel to manage it all. Each piece adds complexity, configuration overhead, and another potential point of failure. This complexity can be a major barrier, especially for indie developers, startups, and anyone looking to prototype an idea quickly.

What if you could have all of that in a single, self-contained file? That's the radical promise of **PocketBase**, an open-source, all-in-one backend written in Go. It bundles a database, real-time API, authentication, and a beautiful admin dashboard into one executable that you can run anywhere. It's a Backend-as-a-Service (BaaS) like Firebase or Supabase, but one that you can host yourself with zero effort.

This article explores what makes PocketBase a compelling choice for your next project, its core features, and how you can use it both as a standalone service and as a powerful Go framework to add custom functionality.

---

### What is PocketBase? The Backend in a Single File 📦

PocketBase is a single, portable executable that provides a complete backend system. When you run it, you instantly get:

- **An Embedded SQLite Database**: Leverages the power and reliability of SQLite in a single database file, eliminating the need for external database servers.
- **A Built-in Admin Dashboard**: A clean, intuitive web UI to manage your database schema, users, files, and access control rules without writing a single line of code.
- **User Authentication**: Ready-to-use auth with email/password, social logins via OAuth2 (Google, GitHub, etc.), and email verification/password reset flows.
- **Real-time Subscriptions**: The ability to subscribe to database changes in real-time, perfect for building collaborative or live-updating applications.
- **A REST-ish API**: As soon as you define a data "collection" (table) in the admin UI, PocketBase automatically generates a full set of secure CRUD API endpoints with powerful filtering, sorting, and expansion capabilities.

The deployment story is its most remarkable feature: you download the binary for your OS, run it, and you have a production-ready backend. It's that simple.

---

### Core Features in Detail 🚀

Let's break down the features that make PocketBase so efficient for developers.

#### The Admin Dashboard: Your Control Center

The first thing you interact with is the admin dashboard, and it's where PocketBase truly shines. From this UI, you can visually define your database collections, add fields (text, number, boolean, JSON, relations, etc.), and immediately see the results. You don't need to write migrations or use an ORM.

Crucially, the dashboard is also where you define **API Rules**. These are security rules that control who can perform what action (create, read, update, delete) on your data, using a simple syntax that can reference the authenticated user's properties.

#### Instant Authentication and Access Control

Setting up secure authentication is often a time-consuming and error-prone task. PocketBase handles it out of the box. You get a full-featured user management system with secure password handling and easy integration for third-party OAuth2 providers. This alone can save days or weeks of development time.

#### Real-time, On-Demand

For any collection you create, you can subscribe to changes from your client-side application. When a record is created, updated, or deleted, PocketBase pushes the changes to all subscribed clients. This enables you to build dynamic, real-time features with minimal effort.

#### Built-in File Storage

PocketBase provides a simple and secure way to handle file uploads. You can attach files to any record, and PocketBase manages the storage, serving, and access control for you. It even supports generating thumbnails on the fly and can be configured to use an S3-compatible service as its storage backend.

---

### Two Ways to Use PocketBase: Standalone vs. Framework

PocketBase offers two primary modes of operation, catering to different levels of complexity.

#### 1. As a Standalone Application

This is the most common and straightforward way to use PocketBase. You run the executable, and it serves the Admin UI and the API. Your frontend application (built with React, Vue, Svelte, etc.) then interacts with the PocketBase API using its client-side JavaScript SDK. This is the "self-hosted Firebase" model, giving you incredible speed for MVPs, internal tools, or simple app backends.

#### 2. As a Go Framework

This is where PocketBase's true power and flexibility emerge. You can import PocketBase as a Go library into your own application. This allows you to "extend" the core functionality with custom server-side logic. You can:

- Add your own custom API routes that perform complex business logic.
- Use **event hooks** to run code before or after a database event occurs (e.g., `OnRecordBeforeCreate`, `OnRecordAfterUpdate`).
- Integrate with other services, send emails, or process payments.
- Schedule custom background jobs (cron).

---

### A Practical Go Framework Example

Let's see how simple it is to extend PocketBase. In this example, we'll start a PocketBase instance and add a custom API route and an event hook.

```go
package main

import (
	"log"
	"net/http"
	"os"

	"github.com/labstack/echo/v5"
	"github.com/pocketbase/pocketbase"
	"github.com/pocketbase/pocketbase/apis"
	"github.com/pocketbase/pocketbase/core"
)

func main() {
	// Create a new PocketBase app instance
	app := pocketbase.New()

	// --- 1. Add a custom API route ---
	// This runs before the default PocketBase routes.
	app.OnBeforeServe().Add(func(e *core.ServeEvent) error {
		// e.Router is an Echo router instance
		e.Router.AddRoute(echo.Route{
			Method: http.MethodGet,
			Path:   "/api/hello",
			Handler: func(c echo.Context) error {
				return c.JSON(http.StatusOK, map[string]string{"message": "Hello from our custom Go route!"})
			},
			// Add middleware to protect the route (e.g., require admin auth)
			Middlewares: []echo.MiddlewareFunc{
				apis.RequireAdminAuth(),
			},
		})
		return nil
	})

	// --- 2. Add an event hook ---
	// This hook fires right before a new record in the 'posts' collection is created.
	app.OnRecordBeforeCreateRequest("posts").Add(func(e *core.RecordCreateEvent) error {
		log.Printf("A new post is about to be created with data: %v", e.Record.PublicExport())

		// You could add validation logic here, or modify the record before saving.
		// For example, let's set a default 'author' if it's not provided.
		if e.Record.GetString("author") == "" {
			e.Record.Set("author", "anonymous")
		}

		return nil
	})

	// Start the app
	if err := app.Start(); err != nil {
		log.Fatal(err)
	}
}
```

This small amount of Go code gives you complete control to build complex, server-side functionality on top of the solid foundation that PocketBase provides.

---

### Conclusion: Who is PocketBase For?

PocketBase is a phenomenal tool, but it's important to understand its ideal use cases.

- **It's perfect for**: Rapid prototyping, MVPs, indie developers, internal tools, and small to medium-sized applications where development speed and simplicity are paramount.
- **It might not be the best fit for**: Large-scale, distributed systems requiring horizontal scaling and extremely high concurrent write loads, as it is fundamentally built on a single SQLite database file.

By bundling a database, auth, and API into a single, easy-to-manage package, PocketBase drastically lowers the barrier to building and launching full-stack applications. Whether you use it as a standalone BaaS or as an extensible Go framework, it's a powerful tool that brings joy and simplicity back to backend development.


What makes PocketBase a compelling choice for your next project? What are its core features, and how you can use it both as a standalone service and as a powerful Go framework to add custom functionality.

medium_pocketbase.png

small_pocketbase.png

thumbnail_pocketbase.png

pocketbase.png

現代のウェブアプリケーションを構築することは、しばしば複雑なパズルを組み立てる作業のように感じられる。データベース、ORM、API フレームワーク、認証システム、ファイルストレージソリューション、そしてそれら全てを管理するための管理パネルが必要になる。それぞれの要素が複雑さ、設定のオーバーヘッド、そして新たな障害点を追加する。この複雑さは、特に個人開発者、スタートアップ、そしてアイデアを迅速にプロトタイプしたい人々にとって、大きな障壁となり得る。

もし、それら全てを単一の自己完結型ファイルで手に入れることができたらどうだろうか？それが、Go で書かれたオープンソースのオールインワンバックエンド、**PocketBase**が掲げる革新的な約束である。PocketBase は、データベース、リアルタイム API、認証、そして美しい管理ダッシュボードを一つの実行可能ファイルにバンドルし、どこでも実行することができる。これは Firebase や Supabase のような Backend-as-a-Service（BaaS）だが、自分で、しかも手間なくホスティングできるものだ。

この記事では、PocketBase が次のプロジェクトにとって魅力的な選択肢となる理由、その主要な機能、そしてスタンドアロンサービスとして、またカスタム機能を追加するための強力な Go フレームワークとして、どのように使用できるかを探求する。

---

### PocketBase とは何か？ 単一ファイルに収まるバックエンド 📦

PocketBase は、完全なバックエンドシステムを提供する、単一のポータブルな実行可能ファイルである。これを実行すると、即座に以下のものが手に入る。

- **組み込み SQLite データベース**: SQLite のパワーと信頼性を単一のデータベースファイルで活用し、外部データベースサーバーの必要性を排除する。
- **内蔵管理ダッシュボード**: データベーススキーマ、ユーザー、ファイル、アクセス制御ルールを一行のコードも書くことなく管理できる、クリーンで直感的なウェブ UI。
- **ユーザー認証**: メール/パスワード、OAuth2 経由のソーシャルログイン（Google、GitHub など）、メール検証/パスワードリセットのフローがすぐに使える形で提供される。
- **リアルタイムサブスクリプション**: データベースの変更をリアルタイムで購読する機能。共同作業やライブ更新を行うアプリケーションの構築に最適だ。
- **REST 風 API**: 管理 UI でデータ「コレクション」（テーブル）を定義するとすぐに、PocketBase は強力なフィルタリング、ソート、展開機能を備えた、安全な CRUD API エンドポイントの完全なセットを自動的に生成する。

その最も注目すべき特徴は、デプロイの容易さだ。OS 用のバイナリをダウンロードし、実行するだけで、本番環境に対応したバックエンドが手に入る。それほどまでにシンプルなのである。

---

### 主要機能の詳細 🚀

PocketBase を開発者にとって非常に効率的にしている機能を詳しく見ていこう。

#### 管理ダッシュボード：あなたのコントロールセンター

最初に触れることになる管理ダッシュボードこそ、PocketBase が真に輝く場所だ。この UI から、データベースコレクションを視覚的に定義し、フィールド（テキスト、数値、ブーリアン、JSON、リレーションなど）を追加し、その結果を即座に確認できる。マイグレーションを書いたり、ORM を使ったりする必要はない。

決定的に重要なのは、このダッシュボードが**API ルール**を定義する場所でもあるという点だ。これらは、認証されたユーザーのプロパティを参照できるシンプルな構文を使い、誰がどのデータに対してどのアクション（作成、読み取り、更新、削除）を実行できるかを制御するセキュリティルールである。

#### 即時利用可能な認証とアクセス制御

安全な認証機能の設定は、時間がかかり、間違いやすい作業であることが多い。PocketBase はそれを標準で処理する。安全なパスワード処理と、サードパーティ OAuth2 プロバイダーとの簡単な統合を備えた、フル機能のユーザー管理システムが手に入る。これだけでも、数日から数週間の開発時間を節約できる可能性がある。

#### オンデマンドのリアルタイム機能

作成した任意のコレクションに対して、クライアントサイドアプリケーションから変更を購読することができる。レコードが作成、更新、または削除されると、PocketBase はその変更を購読している全てのクライアントにプッシュする。これにより、最小限の労力で動的なリアルタイム機能を構築できる。

### 内蔵ファイルストレージ

PocketBase は、ファイルアップロードを処理するためのシンプルで安全な方法を提供する。任意のレコードにファイルを添付でき、PocketBase がストレージ、配信、そしてアクセス制御を管理する。さらに、その場でサムネイルを生成したり、ストレージバックエンドとして S3 互換サービスを使用するように設定することもサポートしている。

---

### PocketBase の二つの使い方：スタンドアロン vs. フレームワーク

PocketBase は、異なる複雑さのレベルに対応するため、二つの主要な動作モードを提供する。

#### 1. スタンドアロンアプリケーションとして

これは PocketBase を使用する最も一般的で直接的な方法だ。実行可能ファイルを実行すると、管理 UI と API が提供される。そして、フロントエンドアプリケーション（React、Vue、Svelte などで構築）が、クライアントサイドの JavaScript SDK を使用して PocketBase API と対話する。これは「セルフホスト版 Firebase」モデルであり、MVP、社内ツール、またはシンプルなアプリのバックエンドに対して信じられないほどの開発速度を提供する。

#### 2. Go フレームワークとして

ここに PocketBase の真のパワーと柔軟性が現れる。PocketBase を Go ライブラリとして自身のアプリケーションにインポートすることができるのだ。これにより、コア機能をカスタムのサーバーサイドロジックで「拡張」できる。

- 複雑なビジネスロジックを実行する独自のカスタム API ルートを追加する。
- データベースイベントが発生する前後にコードを実行するために**イベントフック**を使用する（例：`OnRecordBeforeCreate`、`OnRecordAfterUpdate`）。
- 他のサービスと統合したり、メールを送信したり、支払いを処理したりする。
- カスタムのバックグラウンドジョブ（cron）をスケジュールする。

---

### Go フレームワークとしての実践的な例

PocketBase を拡張するのがいかに簡単か見てみよう。この例では、PocketBase インスタンスを起動し、カスタム API ルートとイベントフックを追加する。

```go
package main

import (
	"log"
	"net/http"
	"os"

	"github.com/labstack/echo/v5"
	"github.com/pocketbase/pocketbase"
	"github.com/pocketbase/pocketbase/apis"
	"github.com/pocketbase/pocketbase/core"
)

func main() {
	// 新しいPocketBaseアプリインスタンスを作成
	app := pocketbase.New()

	// --- 1. カスタムAPIルートを追加 ---
	// これはデフォルトのPocketBaseルートより先に実行される。
	app.OnBeforeServe().Add(func(e *core.ServeEvent) error {
		// e.RouterはEchoのルーターインスタンス
		e.Router.AddRoute(echo.Route{
			Method: http.MethodGet,
			Path:   "/api/hello",
			Handler: func(c echo.Context) error {
				return c.JSON(http.StatusOK, map[string]string{"message": "カスタムGoルートからのHello!"})
			},
			// ルートを保護するためのミドルウェアを追加（例：管理者認証を要求）
			Middlewares: []echo.MiddlewareFunc{
				apis.RequireAdminAuth(),
			},
		})
		return nil
	})

	// --- 2. イベントフックを追加 ---
	// このフックは'posts'コレクションに新しいレコードが作成される直前に発火する。
	app.OnRecordBeforeCreateRequest("posts").Add(func(e *core.RecordCreateEvent) error {
		log.Printf("新しい投稿が次のデータで作成されようとしています: %v", e.Record.PublicExport())

		// ここでバリデーションロジックを追加したり、保存前にレコードを修正したりできる。
		// 例えば、'author'が提供されていない場合にデフォルト値を設定する。
		if e.Record.GetString("author") == "" {
			e.Record.Set("author", "anonymous")
		}

		return nil
	})

	// アプリを起動
	if err := app.Start(); err != nil {
		log.Fatal(err)
	}
}
```

この少量の Go コードで、PocketBase が提供する堅固な基盤の上に、複雑なサーバーサイド機能を構築するための完全なコントロールが得られる。

---

### 結論：PocketBase は誰のためのものか？

PocketBase は驚異的なツールだが、その理想的なユースケースを理解することが重要だ。

- **最適な対象**: 迅速なプロトタイピング、MVP、個人開発者、社内ツール、そして開発速度とシンプルさが最優先される中小規模のアプリケーション。
- **あまり適していない可能性のある対象**: 水平スケーリングと極めて高い同時書き込み負荷を必要とする大規模な分散システム。これは、根本的に単一の SQLite データベースファイル上に構築されているためである。

データベース、認証、API を単一で管理しやすいパッケージにバンドルすることで、PocketBase はフルスタックアプリケーションの構築と立ち上げの障壁を劇的に下げる。スタンドアロンの BaaS として使うにせよ、拡張可能な Go フレームワークとして使うにせよ、それはバックエンド開発に喜びとシンプルさを取り戻してくれる強力なツールである。


PocketBase が次のプロジェクトにとって魅力的な選択肢となる理由、その主要な機能、そしてスタンドアロンサービスとして、またカスタム機能を追加するための強力な Go フレームワークとして、どのように使用できるかを探求する。

スタックを簡素化する：PocketBase への深掘り

Simplify Your Stack: A Deep Dive into PocketBase

Modern web applications are a far cry from the static documents of the early internet. They are dynamic, interactive, and increasingly expected to work offline. To build these rich experiences, applications need a way to remember things on the user's device—from simple user preferences to complex data for offline use. This is where browser storage comes in.

For a long time, "cookies" were the only game in town, but today's browser provides a sophisticated toolbox of storage mechanisms. Each tool is designed for a different purpose, with unique strengths and limitations regarding capacity, persistence, and performance. Choosing the right tool for the job is crucial for building a fast and reliable application.

This article provides a comprehensive guide to the four main browser storage types: **Cookies**, **Web Storage (LocalStorage & SessionStorage)**, **IndexedDB**, and the **Cache API**. We'll explore what each one is, its ideal use case, and its key characteristics to help you make informed decisions in your next project.

---

### 1. Cookies 🍪 - The Veteran

Cookies are the original client-side storage mechanism. At their core, they are small pieces of data that a server sends to the user's browser. The browser then stores this data and sends it back with every subsequent request to the same server.

- **Primary Use Case**: **Session Management and Tracking.** Because cookies are sent with every HTTP request, they are perfect for telling the server who you are. This is how servers maintain a login session (using a session ID stored in a cookie), personalize content, and track user behavior across different pages.

- **Key Characteristics**:

  - **Tiny Capacity**: Limited to about 4KB of data, making them unsuitable for storing anything substantial.
  - **Performance Overhead**: Being sent with _every single request_ to your domain (including images, CSS, etc.) adds unnecessary overhead and can slow down your application.
  - **Server and Client Access**: They can be set and read by both the server (via `Set-Cookie` headers) and the client (via `document.cookie`).
  - **Expiration**: Cookies have a configurable expiration date, after which they are automatically deleted.

- **When to use**: Use cookies only when the server needs to know a piece of information on every request. The most common and valid use case today is for storing authentication tokens or session identifiers. **Avoid using cookies for storing general application state.**

---

### 2. Web Storage (LocalStorage & SessionStorage) 📦 - The Workhorse

The Web Storage API was introduced as a modern, more straightforward successor to cookies for client-side storage needs. It provides a simple synchronous key-value store directly in the browser, and critically, the data is **not** sent to the server with every request.

Web Storage is split into two distinct mechanisms:

1.  **LocalStorage**: Data stored in `localStorage` is persistent. It remains stored in the browser even after the user closes the tab, closes the browser, or reboots their computer. The data only disappears when the user manually clears their browser cache or the web app programmatically deletes it.

2.  **SessionStorage**: Data stored in `sessionStorage` is temporary. It is tied to a specific browser tab or window session. When the user closes that tab, the data is gone forever.

- **Primary Use Case**: **Storing Application UI State and User Preferences.** This includes things like a user's theme preference (dark/light mode), whether a welcome message has been dismissed, or the contents of a form that you want to save between page loads.

- **Key Characteristics**:

  - **Larger Capacity**: Offers significantly more space than cookies, typically around 5-10MB per domain.
  - **Client-Side Only**: The data is purely for the client and is not automatically transmitted to the server.
  - **Simple Synchronous API**: Provides an easy-to-use, synchronous API (`setItem()`, `getItem()`, `removeItem()`). While simple, being synchronous means it can block the main browser thread if used excessively with large data.
  - **String-Only Storage**: It can only store strings. To store complex objects, you must manually serialize them to a JSON string with `JSON.stringify()` and deserialize them with `JSON.parse()`.

- **When to use**: `localStorage` is the default choice for storing small-to-medium amounts of simple, non-critical data that needs to persist across sessions. `sessionStorage` is perfect for temporary data related to a single user task within one tab.

---

### 3. IndexedDB 🗄️ - The Powerhouse

When your client-side storage needs go beyond simple key-value pairs, you need a real database. **IndexedDB** is exactly that: a low-level, transactional, object-oriented database built into the browser.

- **Primary Use Case**: **Building Offline-First Applications and PWAs.** IndexedDB is designed for storing large amounts of structured data, enabling applications to work reliably without a network connection. Think of email clients, content creation tools, or any app that needs to manage a significant dataset on the client.

- **Key Characteristics**:

  - **Massive Capacity**: Storage limits are much larger than Web Storage (often multiple gigabytes) and are based on the user's available disk space. The browser will typically prompt the user for permission when an app requests a large amount of storage.
  - **Stores Complex Objects**: It can store almost any complex JavaScript object directly, without the need for manual JSON serialization.
  - **Asynchronous API**: Its API is fully asynchronous (using events or Promises), meaning it doesn't block the main UI thread. This is essential for performance when dealing with large amounts of data.
  - **Transactional and Indexed**: It supports ACID-like transactions to ensure data integrity. You can create indexes on your data, allowing for efficient, high-performance querying.

- **When to use**: Choose IndexedDB when you need to store a large, structured dataset on the client, require offline capabilities, or need to perform complex queries. Its API can be complex, so developers often use a lightweight wrapper library like `idb` or `Dexie.js` to simplify interactions.

---

### 4. Cache API (CacheStorage) ⚡ - The Specialist

The **Cache API** is a specialized storage mechanism with one specific job: storing and managing network requests and their corresponding responses. It is a fundamental part of the Service Worker lifecycle.

- **Primary Use Case**: **Enabling Offline Access and Performance Caching.** A Service Worker can intercept outgoing network requests, check if a valid response already exists in the cache, and serve it directly without hitting the network. This is how PWAs can load instantly and function offline.

- **Key Characteristics**:

  - **Request/Response Pairs**: It stores `Request` and `Response` objects, not arbitrary data like user information.
  - **Service Worker Integration**: It's designed to be used within a Service Worker to implement caching strategies (e.g., cache-first, network-first, stale-while-revalidate).
  - **Asynchronous**: Like IndexedDB, its API is asynchronous and Promise-based.
  - **Large Capacity**: It can store a significant amount of data, such as entire websites' worth of assets (HTML, CSS, JS, images, API responses).

- **When to use**: Use the Cache API exclusively for caching network resources to improve application performance and enable offline functionality. It is **not** a general-purpose data store.

---

### Conclusion: Choosing the Right Tool

| Storage Type       | Primary Use Case    | Capacity    | Persistence     | API Type  |
| :----------------- | :------------------ | :---------- | :-------------- | :-------- |
| **Cookies**        | Session Management  | ~4KB        | Expires         | Sync      |
| **LocalStorage**   | Persistent UI State | ~5-10MB     | Manual Deletion | Sync      |
| **SessionStorage** | Temporary UI State  | ~5-10MB     | Per Tab Session | Sync      |
| **IndexedDB**      | Offline App Data    | Large (GBs) | Manual Deletion | **Async** |
| **Cache API**      | Network Responses   | Large (GBs) | Manual Deletion | **Async** |

There is no single "best" browser storage. The modern web provides a layered set of tools, each tailored to a specific need. By understanding the trade-offs between them, you can build more sophisticated, performant, and reliable web applications that meet the high expectations of today's users.


This article provides a comprehensive guide to the four main browser storage types: Cookies, Web Storage (LocalStorage & SessionStorage), IndexedDB, and the Cache API.

small_web-storage-api.png

thumbnail_web-storage-api.png

web-storage-api.png

現代のウェブアプリケーションは、初期のインターネットの静的な文書とは大きく異なる。動的でインタラクティブであり、オフラインで動作することさえもますます期待されるようになっている。こうしたリッチな体験を構築するために、アプリケーションはユーザーのデバイス上で情報を記憶する方法を必要とする。それは、単純なユーザー設定からオフラインで使用する複雑なデータまで様々だ。ここでブラウザストレージの出番となる。

長らく「Cookie」が唯一の選択肢であったが、今日のブラウザは洗練されたストレージ機構のツールボックスを提供している。各ツールは異なる目的のために設計されており、容量、永続性、パフォーマンスに関して独自の長所と短所を持つ。目的に合った適切なツールを選ぶことは、高速で信頼性の高いアプリケーションを構築する上で極めて重要である。

この記事では、主要な 4 つのブラウザストレージタイプ、**Cookie**、**ウェブストレージ（LocalStorage & SessionStorage）**、**IndexedDB**、そして**Cache API**について包括的に解説する。それぞれが何であるか、理想的なユースケース、そして主要な特徴を探り、あなたの次のプロジェクトで情報に基づいた意思決定を下す手助けをする。

---

### 1. Cookie 🍪 - 古参

Cookie は、元祖クライアントサイドストレージ機構である。その核心は、サーバーがユーザーのブラウザに送信する小さなデータ片だ。ブラウザはそのデータを保存し、以降同じサーバーへのリクエストのたびにそれを送り返す。

- **主なユースケース**: **セッション管理とトラッキング**。Cookie は HTTP リクエストごとに送信されるため、サーバーに対してあなたが誰であるかを伝えるのに最適だ。サーバーがログインセッションを維持したり（Cookie に保存されたセッション ID を使用）、コンテンツをパーソナライズしたり、異なるページ間でのユーザー行動を追跡したりするのは、この仕組みによるものである。

- **主な特徴**:

  - **極小の容量**: 約 4KB のデータに制限されており、実質的なものを保存するには不向きだ。
  - **パフォーマンスのオーバーヘッド**: あなたのドメインへの*全てのリクエスト*（画像、CSS などを含む）と共に送信されるため、不要なオーバーヘッドが生じ、アプリケーションの速度を低下させる可能性がある。
  - **サーバーとクライアントからのアクセス**: サーバー（`Set-Cookie`ヘッダー経由）とクライアント（`document.cookie`経由）の両方で設定・読み取りが可能だ。
  - **有効期限**: Cookie には設定可能な有効期限があり、それを過ぎると自動的に削除される。

- **使用する場面**: サーバーがリクエストごとに情報を知る必要がある場合にのみ使用すべきだ。今日における最も一般的で正当なユースケースは、認証トークンやセッション識別子の保存である。**一般的なアプリケーションの状態を保存するために Cookie を使用するのは避けるべきだ。**

---

### 2. ウェブストレージ (LocalStorage & SessionStorage) 📦 - 主力

ウェブストレージ API は、クライアントサイドのストレージニーズに応えるため、Cookie の現代的でより直接的な後継として導入された。これはブラウザ内でシンプルな同期的なキーバリューストアを提供し、決定的に重要なのは、データがリクエストごとにサーバーに送信され**ない**ことだ。

ウェブストレージは、2 つの異なる機構に分かれている。

1.  **LocalStorage**: `localStorage`に保存されたデータは永続的だ。ユーザーがタブを閉じても、ブラウザを閉じても、コンピュータを再起動しても、ブラウザ内に保存され続ける。データは、ユーザーが手動でブラウザキャッシュをクリアするか、ウェブアプリがプログラムで削除した場合にのみ消える。

2.  **SessionStorage**: `sessionStorage`に保存されたデータは一時的なものだ。特定のブラウザタブまたはウィンドウのセッションに紐づいている。ユーザーがそのタブを閉じると、データは永久に失われる。

- **主なユースケース**: **アプリケーションの UI 状態やユーザー設定の保存**。これには、ユーザーのテーマ設定（ダーク/ライトモード）、ウェルカムメッセージを非表示にしたかどうか、ページをまたいで保存したいフォームの内容などが含まれる。

- **主な特徴**:

  - **より大きな容量**: Cookie よりも大幅に多くのスペースを提供し、通常はドメインごとに約 5〜10MB である。
  - **クライアントサイド専用**: データは純粋にクライアント用であり、サーバーに自動的に送信されることはない。
  - **シンプルな同期的 API**: 使いやすい同期的 API（`setItem()`、`getItem()`、`removeItem()`）を提供する。シンプルである一方、同期的であるため、大量のデータで過度に使用するとメインのブラウザスレッドをブロックする可能性がある。
  - **文字列専用ストレージ**: 文字列しか保存できない。複雑なオブジェクトを保存するには、`JSON.stringify()`で手動で JSON 文字列にシリアライズし、`JSON.parse()`でデシリアライズする必要がある。

- **使用する場面**: セッションをまたいで永続させる必要がある、重要度の低い単純なデータを少量から中量保存する場合、`localStorage`が標準的な選択肢となる。`sessionStorage`は、単一タブ内の一つのユーザータスクに関連する一時的なデータに最適だ。

---

### 3. IndexedDB 🗄️ - 強力なデータベース

クライアントサイドのストレージニーズが単純なキーバリューペアを超える場合、本格的なデータベースが必要になる。**IndexedDB**はまさにそれであり、ブラウザに組み込まれた低レベルのトランザクション対応オブジェクト指向データベースである。

- **主なユースケース**: **オフラインファーストなアプリケーションと PWA の構築**。IndexedDB は、大量の構造化データを保存するために設計されており、ネットワーク接続なしでアプリケーションが確実に動作することを可能にする。メールクライアント、コンテンツ作成ツール、あるいはクライアント側で大量のデータセットを管理する必要があるあらゆるアプリを想像してみよう。

- **主な特徴**:

  - **巨大な容量**: ストレージの上限はウェブストレージよりもはるかに大きく（しばしば数ギガバイト）、ユーザーの利用可能なディスク容量に基づく。アプリが大量のストレージを要求すると、通常ブラウザはユーザーに許可を求めるプロンプトを表示する。
  - **複雑なオブジェクトの保存**: 手動での JSON シリアライズを必要とせず、ほとんどの複雑な JavaScript オブジェクトを直接保存できる。
  - **非同期的 API**: API は完全に非同期（イベントまたは Promise を使用）であり、メインの UI スレッドをブロックしない。これは大量のデータを扱う際のパフォーマンスにとって不可欠だ。
  - **トランザクションとインデックス対応**: データの整合性を保証するために ACID ライクなトランザクションをサポートする。データにインデックスを作成でき、効率的で高性能なクエリが可能になる。

- **使用する場面**: クライアント側で大規模な構造化データセットを保存する必要がある場合、オフライン機能が必要な場合、または複雑なクエリを実行する必要がある場合に IndexedDB を選択する。API が複雑なため、開発者はしばしば`idb`や`Dexie.js`のような軽量なラッパーライブラリを使用してインタラクションを簡素化する。

---

### 4. Cache API (CacheStorage) ⚡ - スペシャリスト

**Cache API**は、特定の単一の仕事、すなわちネットワークリクエストとそれに対応するレスポンスを保存・管理するために特化したストレージ機構である。これはサービスワーカーのライフサイクルの基本的な部分をなす。

- **主なユースケース**: **オフラインアクセスとパフォーマンスキャッシングの実現**。サービスワーカーは送信されるネットワークリクエストを傍受し、有効なレスポンスがキャッシュに既に存在するかどうかを確認し、ネットワークに接続することなく直接それを提供できる。PWA が即座に読み込まれ、オフラインで機能するのはこの仕組みによるものだ。

- **主な特徴**:

  - **リクエスト/レスポンスのペア**: ユーザー情報のような任意のデータではなく、`Request`および`Response`オブジェクトを保存する。
  - **サービスワーカーとの統合**: キャッシング戦略（例：キャッシュファースト、ネットワークファースト、stale-while-revalidate）を実装するために、サービスワーカー内で使用されるように設計されている。
  - **非同期的**: IndexedDB と同様に、API は非同期的で Promise ベースである。
  - **大容量**: ウェブサイト全体のアセット（HTML、CSS、JS、画像、API レスポンス）など、大量のデータを保存できる。

- **使用する場面**: アプリケーションのパフォーマンスを向上させ、オフライン機能を有効にするために、ネットワークリソースをキャッシングする目的でのみ Cache API を使用する。これは**汎用のデータストアではない**。

---

### 結論：適切なツールの選択

| ストレージタイプ   | 主なユースケース       | 容量             | 永続性           | API タイプ |
| :----------------- | :--------------------- | :--------------- | :--------------- | :--------- |
| **Cookie**         | セッション管理         | ~4KB             | 有効期限あり     | 同期       |
| **LocalStorage**   | 永続的な UI 状態       | ~5-10MB          | 手動削除         | 同期       |
| **SessionStorage** | 一時的な UI 状態       | ~5-10MB          | タブセッション毎 | 同期       |
| **IndexedDB**      | オフラインアプリデータ | 大容量 (GB 単位) | 手動削除         | **非同期** |
| **Cache API**      | ネットワーク応答       | 大容量 (GB 単位) | 手動削除         | **非同期** |

単一の「最良の」ブラウザストレージは存在しない。現代のウェブは、特定のニーズに合わせて調整された階層的なツールセットを提供している。それらの間のトレードオフを理解することで、今日のユーザーの高い期待に応える、より洗練され、パフォーマンスが高く、信頼性のあるウェブアプリケーションを構築できるのだ。


主要な 4 つのブラウザストレージタイプ、Cookie、ウェブストレージ（LocalStorage & SessionStorage）、IndexedDB、そしてCache APIについて包括的に解説する。

Cookie だけじゃない：最新ブラウザストレージ入門

More Than Just Cookies: A Guide to Modern Browser Storage

gRPC has emerged as a powerful framework for building high-performance, cross-platform APIs. At its core, it leverages HTTP/2 for transport and Protocol Buffers as its interface definition language, enabling efficient and strongly-typed communication between microservices. While many developers start with the basic request-response pattern, the true power of gRPC lies in its four distinct communication models. Understanding these patterns is key to designing robust and scalable systems.

In this article, we'll explore each of the four gRPC communication patterns—Unary, Server Streaming, Client Streaming, and Bidirectional Streaming—by implementing a simple chat service in Go. We will walk through the `.proto` definition, server-side handlers, and client-side logic for each pattern.

---

### Prerequisites & Setup

Before we dive in, make sure you have the Go programming language and the Protocol Buffers compiler (`protoc`) installed. You'll also need the Go plugins for gRPC and Protobufs:

```shell
go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.28
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@v1.2
```

First, let's define our service in a `.proto` file. We'll create a `ChatService` with a method for each of the four communication types.

**`chat/chat.proto`**

```protobuf
syntax = "proto3";

package chat;

option go_package = "[github.com/your-repo/grpc-blog/chat](https://github.com/your-repo/grpc-blog/chat)";

// The request message containing the user's name and message.
message Message {
  string user = 1;
  string content = 2;
}

// The service definition.
service ChatService {
  // Unary RPC: Sends a single message and gets a single response.
  rpc SayHello(Message) returns (Message) {}

  // Server Streaming RPC: Sends a single message and gets a stream of responses.
  rpc BroadcastMessages(Message) returns (stream Message) {}

  // Client Streaming RPC: Sends a stream of messages and gets a single response.
  rpc UploadStream(stream Message) returns (Message) {}

  // Bidirectional Streaming RPC: Sends a stream of messages and gets a stream of responses.
  rpc ChatStream(stream Message) returns (stream Message) {}
}
```

After defining the service, we generate the Go code using `protoc`:

```shell
protoc --go_out=. --go_opt=paths=source_relative \
    --go-grpc_out=. --go-grpc_opt=paths=source_relative \
    chat/chat.proto
```

This command generates `chat/chat.pb.go` and `chat/chat_grpc.pb.go`, which contain the necessary interfaces and structs for our server and client.

---

### 1. Unary RPC

The **Unary RPC** is the simplest pattern, mirroring a traditional function call. The client sends a single request message to the server and receives a single response message back.

#### Server Implementation

On the server, we implement the `SayHello` method defined in our `ChatServiceServer` interface. It takes a context and the request message as arguments and returns a response message and an error.

```go
// server/main.go
type server struct {
    chat.UnimplementedChatServiceServer
}

func (s *server) SayHello(ctx context.Context, in *chat.Message) (*chat.Message, error) {
    log.Printf("Received Unary message from %s: %s", in.User, in.Content)
    return &chat.Message{
        User:    "Server",
        Content: "Hello, " + in.User + "! Thanks for your message.",
    }, nil
}
```

#### Client Implementation

The client creates a connection, instantiates a new client stub, and calls the remote method just like a local function.

```go
// client/main.go
c := chat.NewChatServiceClient(conn)
ctx, cancel := context.WithTimeout(context.Background(), time.Second)
defer cancel()

res, err := c.SayHello(ctx, &chat.Message{User: "Marko", Content: "This is a unary call."})
if err != nil {
    log.Fatalf("could not greet: %v", err)
}
log.Printf("Unary Response from %s: %s", res.User, res.Content)
```

**Use Cases:** Perfect for simple, self-contained operations like creating a resource, fetching a user profile, or performing a status check.

---

### 2. Server Streaming RPC

In a **Server Streaming RPC**, the client sends a single request, but the server responds with a stream of messages. The server keeps the connection open and sends multiple messages back until it has no more data to send.

#### Server Implementation

The server method receives the request and a stream object. It can then use the stream's `Send()` method multiple times to send back responses.

```go
// server/main.go
func (s *server) BroadcastMessages(in *chat.Message, stream chat.ChatService_BroadcastMessagesServer) error {
    log.Printf("Received Broadcast request from %s", in.User)
    messages := []chat.Message{
        {User: "Server", Content: "Welcome to the broadcast!"},
        {User: "Server", Content: "Here is message #1."},
        {User: "Server", Content: "And here is message #2."},
        {User: "Server", Content: "Broadcast finished."},
    }

    for _, msg := range messages {
        if err := stream.Send(&msg); err != nil {
            return err
        }
        time.Sleep(500 * time.Millisecond) // Simulate work
    }
    return nil
}
```

#### Client Implementation

The client calls the method and receives a stream object in return. It then enters a loop, calling `Recv()` to read messages from the stream until it receives an `io.EOF` error, which signals that the stream has been closed by the server.

```go
// client/main.go
stream, err := c.BroadcastMessages(ctx, &chat.Message{User: "Marko"})
if err != nil {
    log.Fatalf("could not open broadcast stream: %v", err)
}

for {
    msg, err := stream.Recv()
    if err == io.EOF {
        // Stream finished
        break
    }
    if err != nil {
        log.Fatalf("failed to receive broadcast message: %v", err)
    }
    log.Printf("Broadcast from %s: %s", msg.User, msg.Content)
}
```

**Use Cases:** Ideal for scenarios where a server needs to push updates to a client, such as stock tickers, live sports scores, or progress notifications for a long-running task.

---

### 3. Client Streaming RPC

The **Client Streaming RPC** is the inverse of server streaming. The client sends a sequence of messages to the server using a stream. Once the client has finished writing messages, it waits for the server to process them and return a single response.

#### Server Implementation

The server's handler receives a stream object. It uses a loop with `Recv()` to read all incoming messages from the client. When the client closes the stream, `Recv()` returns an `io.EOF` error. The server can then perform its final calculations and send a single response using `SendAndClose()`.

```go
// server/main.go
func (s *server) UploadStream(stream chat.ChatService_UploadStreamServer) error {
    var messageCount int32
    var lastUser string
    for {
        msg, err := stream.Recv()
        if err == io.EOF {
            log.Printf("Upload stream finished. Received %d messages.", messageCount)
            return stream.SendAndClose(&chat.Message{
                User:    "Server",
                Content: fmt.Sprintf("Finished receiving stream from %s. Got %d messages.", lastUser, messageCount),
            })
        }
        if err != nil {
            return err
        }
        lastUser = msg.User
        messageCount++
        log.Printf("Received message from client stream: %s", msg.Content)
    }
}
```

#### Client Implementation

The client obtains a stream object by calling the method. It then uses a loop to send multiple messages with `Send()`. After finishing, it calls `CloseAndRecv()` to notify the server that it's done and to receive the final summary response.

```go
// client/main.go
stream, err := c.UploadStream(ctx)
if err != nil {
    log.Fatalf("could not open upload stream: %v", err)
}

messages := []chat.Message{
    {User: "Marko", Content: "Log entry 1"},
    {User: "Marko", Content: "Log entry 2"},
    {User: "Marko", Content: "Log entry 3"},
}

for _, msg := range messages {
    if err := stream.Send(&msg); err != nil {
        log.Fatalf("failed to send message to stream: %v", err)
    }
    time.Sleep(300 * time.Millisecond)
}

res, err := stream.CloseAndRecv()
if err != nil {
    log.Fatalf("failed to receive response from upload stream: %v", err)
}
log.Printf("Upload Stream Response: %s", res.Content)
```

**Use Cases:** Excellent for large data uploads, such as sending log files, IoT device metrics, or chunks of a video file.

---

### 4. Bidirectional Streaming RPC

The **Bidirectional Streaming RPC** is the most flexible model. Both the client and server can send a stream of messages to each other independently over a single gRPC connection. The order of reads and writes is not guaranteed and depends on the application logic.

#### Server Implementation

The server handler receives a stream that can be used for both reading and writing. It can read a message with `Recv()` and write a response with `Send()` at any time.

```go
// server/main.go
func (s *server) ChatStream(stream chat.ChatService_ChatStreamServer) error {
    for {
        in, err := stream.Recv()
        if err == io.EOF {
            return nil
        }
        if err != nil {
            return err
        }
        log.Printf("Received message in ChatStream from %s: %s", in.User, in.Content)

        // Echo the message back
        if err := stream.Send(&chat.Message{User: "Server", Content: "Echo: " + in.Content}); err != nil {
            return err
        }
    }
}
```

#### Client Implementation

The client-side logic is more complex as it needs to handle sending and receiving concurrently. A common pattern is to use two separate goroutines: one for sending messages and one for receiving them. A channel or `sync.WaitGroup` is used to coordinate and signal completion.

```go
// client/main.go
stream, err := c.ChatStream(context.Background()) // Use a background context
if err != nil {
    log.Fatalf("could not open chat stream: %v", err)
}

var wg sync.WaitGroup
wg.Add(2)

// Goroutine for sending messages
go func() {
    defer wg.Done()
    messages := []chat.Message{
        {User: "Marko", Content: "Hi!"},
        {User: "Marko", Content: "How are you?"},
        {User: "Marko", Content: "I'm using a bidi stream!"},
    }
    for _, msg := range messages {
        log.Printf("Sending message: %s", msg.Content)
        if err := stream.Send(&msg); err != nil {
            log.Fatalf("failed to send message: %v", err)
        }
        time.Sleep(time.Second)
    }
    stream.CloseSend() // IMPORTANT: Close the sending side of the stream
}()

// Goroutine for receiving messages
go func() {
    defer wg.Done()
    for {
        res, err := stream.Recv()
        if err == io.EOF {
            return // Server closed the stream
        }
        if err != nil {
            log.Fatalf("failed to receive message: %v", err)
        }
        log.Printf("Received from server: %s", res.Content)
    }
}()

wg.Wait()
log.Println("Bidirectional stream finished.")
```

**Use Cases:** The foundation for complex, interactive applications like real-time chat services, collaborative document editing, or live gaming sessions.

---

### Conclusion

By mastering gRPC's four communication patterns, you unlock the ability to build highly efficient and specialized APIs tailored to your exact needs. While Unary RPCs cover many standard use cases, the streaming patterns provide the power to handle real-time data flow, large datasets, and fully interactive services. Choosing the right pattern is a critical step in designing a resilient and performant microservices architecture with Go and gRPC.


In this article, we'll explore each of the four gRPC communication patterns—Unary, Server Streaming, Client Streaming, and Bidirectional Streaming—by implementing a simple chat service in Go. 

large_grpc.png

medium_grpc.png

small_grpc.png

thumbnail_grpc.png

grpc.png

gRPC は、高性能でクロスプラットフォームな API を構築するための強力なフレームワークとして台頭している。その中核では、トランスポートに HTTP/2 を、インターフェース定義言語に Protocol Buffers を活用し、マイクロサービス間で効率的かつ厳密に型付けされた通信を可能にする。多くの開発者は基本的なリクエスト/レスポンスパターンから始めるが、gRPC の真の力はその 4 つの異なる通信モデルにある。これらのパターンを理解することは、堅牢でスケーラブルなシステムを設計する鍵となる。

この記事では、gRPC の 4 つの通信パターン（Unary、サーバー ストリーミング、クライアント ストリーミング、双方向ストリーミング）のそれぞれを、Go で簡単なチャットサービスを実装しながら探求していく。`.proto`ファイルの定義、サーバー側のハンドラ、そして各パターンのクライアント側のロジックを順に見ていこう。

---

### 前提条件とセットアップ

始める前に、Go プログラミング言語と Protocol Buffers コンパイラ（`protoc`）がインストールされていることを確認する必要がある。また、gRPC と Protobufs の Go プラグインも必要だ。

```shell
go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.28
go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@v1.2
```

まず、`.proto`ファイルでサービスを定義する。4 つの通信タイプごとにメソッドを持つ`ChatService`を作成する。

**`chat/chat.proto`**

```protobuf
syntax = "proto3";

package chat;

option go_package = "github.com/your-repo/grpc-blog/chat";

// ユーザー名とメッセージを含むリクエストメッセージ
message Message {
  string user = 1;
  string content = 2;
}

// サービス定義
service ChatService {
  // Unary RPC: 単一のメッセージを送信し、単一のレスポンスを受け取る
  rpc SayHello(Message) returns (Message) {}

  // Server Streaming RPC: 単一のメッセージを送信し、レスポンスのストリームを受け取る
  rpc BroadcastMessages(Message) returns (stream Message) {}

  // Client Streaming RPC: メッセージのストリームを送信し、単一のレスポンスを受け取る
  rpc UploadStream(stream Message) returns (Message) {}

  // Bidirectional Streaming RPC: メッセージのストリームを送信し、レスポンスのストリームを受け取る
  rpc ChatStream(stream Message) returns (stream Message) {}
}
```

サービスを定義した後、`protoc`を使って Go のコードを生成する。

```shell
protoc --go_out=. --go_opt=paths=source_relative \
    --go-grpc_out=. --go-grpc_opt=paths=source_relative \
    chat/chat.proto
```

このコマンドは`chat/chat.pb.go`と`chat/chat_grpc.pb.go`を生成する。これらには、サーバーとクライアントに必要なインターフェースと構造体が含まれている。

---

### 1. Unary RPC

**Unary RPC**は最もシンプルなパターンで、従来の関数呼び出しに似ている。クライアントはサーバーに単一のリクエストメッセージを送信し、単一のレスポンスメッセージを返してもらう。

### サーバー側実装

サーバー側では、`ChatServiceServer`インターフェースで定義された`SayHello`メソッドを実装する。このメソッドは、コンテキストとリクエストメッセージを引数に取り、レスポンスメッセージとエラーを返す。

```go
// server/main.go
type server struct {
    chat.UnimplementedChatServiceServer
}

func (s *server) SayHello(ctx context.Context, in *chat.Message) (*chat.Message, error) {
    log.Printf("Unaryメッセージ受信 from %s: %s", in.User, in.Content)
    return &chat.Message{
        User:    "Server",
        Content: "こんにちは、" + in.User + "さん！メッセージありがとう。",
    }, nil
}
```

#### クライアント側実装

クライアントは接続を確立し、新しいクライアントスタブをインスタンス化し、ローカル関数のようにリモートメソッドを呼び出す。

```go
// client/main.go
c := chat.NewChatServiceClient(conn)
ctx, cancel := context.WithTimeout(context.Background(), time.Second)
defer cancel()

res, err := c.SayHello(ctx, &chat.Message{User: "Marko", Content: "これはUnary呼び出しだ。"})
if err != nil {
    log.Fatalf("挨拶ができなかった: %v", err)
}
log.Printf("Unaryレスポンス from %s: %s", res.User, res.Content)
```

**ユースケース:** リソースの作成、ユーザープロファイルの取得、ステータスチェックなど、自己完結型の単純な操作に最適である。

---

### 2. サーバー ストリーミング RPC

**サーバー ストリーミング RPC**では、クライアントは単一のリクエストを送信するが、サーバーはメッセージのストリームで応答する。サーバーは接続を開いたままにし、送信するデータがなくなるまで複数のメッセージを返す。

#### サーバー側実装

サーバーメソッドはリクエストとストリームオブジェクトを受け取る。そして、ストリームの`Send()`メソッドを複数回使用してレスポンスを返信できる。

```go
// server/main.go
func (s *server) BroadcastMessages(in *chat.Message, stream chat.ChatService_BroadcastMessagesServer) error {
    log.Printf("Broadcastリクエスト受信 from %s", in.User)
    messages := []chat.Message{
        {User: "Server", Content: "ブロードキャストへようこそ！"},
        {User: "Server", Content: "こちらがメッセージ#1だ。"},
        {User: "Server", Content: "そしてこちらがメッセージ#2。"},
        {User: "Server", Content: "ブロードキャスト終了。"},
    }

    for _, msg := range messages {
        if err := stream.Send(&msg); err != nil {
            return err
        }
        time.Sleep(500 * time.Millisecond) // 処理をシミュレート
    }
    return nil
}
```

#### クライアント側実装

クライアントはメソッドを呼び出し、戻り値としてストリームオブジェクトを受け取る。その後、ループに入り、`Recv()`を呼び出してストリームからメッセージを読み取る。サーバーによってストリームが閉じられると`io.EOF`エラーを受け取り、ループを終了する。

```go
// client/main.go
stream, err := c.BroadcastMessages(ctx, &chat.Message{User: "Marko"})
if err != nil {
    log.Fatalf("ブロードキャストストリームを開けなかった: %v", err)
}

for {
    msg, err := stream.Recv()
    if err == io.EOF {
        // ストリーム終了
        break
    }
    if err != nil {
        log.Fatalf("ブロードキャストメッセージの受信に失敗した: %v", err)
    }
    log.Printf("Broadcast from %s: %s", msg.User, msg.Content)
}
```

**ユースケース:** 株価のティッカー、スポーツのライブスコア、長時間実行されるタスクの進捗通知など、サーバーがクライアントに更新をプッシュする必要があるシナリオに最適だ。

---

### 3. クライアント ストリーミング RPC

**クライアント ストリーミング RPC**はサーバーストリーミングの逆である。クライアントはストリームを使用して一連のメッセージをサーバーに送信する。クライアントがメッセージの書き込みを完了すると、サーバーがそれらを処理し、単一のレスポンスを返すのを待つ。

#### サーバー側実装

サーバーのハンドラはストリームオブジェクトを受け取る。`Recv()`を使ったループで、クライアントからのすべての着信メッセージを読み取る。クライアントがストリームを閉じると、`Recv()`は`io.EOF`エラーを返す。その後、サーバーは最終的な計算を行い、`SendAndClose()`を使用して単一のレスポンスを送信できる。

```go
// server/main.go
func (s *server) UploadStream(stream chat.ChatService_UploadStreamServer) error {
    var messageCount int32
    var lastUser string
    for {
        msg, err := stream.Recv()
        if err == io.EOF {
            log.Printf("アップロードストリーム終了。%d件のメッセージを受信した。", messageCount)
            return stream.SendAndClose(&chat.Message{
                User:    "Server",
                Content: fmt.Sprintf("%sからのストリーム受信完了。%d件のメッセージを取得した。", lastUser, messageCount),
            })
        }
        if err != nil {
            return err
        }
        lastUser = msg.User
        messageCount++
        log.Printf("クライアントストリームからメッセージ受信: %s", msg.Content)
    }
}
```

#### クライアント側実装

クライアントはメソッドを呼び出してストリームオブジェクトを取得する。その後、ループを使用して`Send()`で複数のメッセージを送信する。終了後、`CloseAndRecv()`を呼び出してサーバーに完了を通知し、最終的な要約レスポンスを受け取る。

```go
// client/main.go
stream, err := c.UploadStream(ctx)
if err != nil {
    log.Fatalf("アップロードストリームを開けなかった: %v", err)
}

messages := []chat.Message{
    {User: "Marko", Content: "ログエントリ 1"},
    {User: "Marko", Content: "ログエントリ 2"},
    {User: "Marko", Content: "ログエントリ 3"},
}

for _, msg := range messages {
    if err := stream.Send(&msg); err != nil {
        log.Fatalf("ストリームへのメッセージ送信に失敗した: %v", err)
    }
    time.Sleep(300 * time.Millisecond)
}

res, err := stream.CloseAndRecv()
if err != nil {
    log.Fatalf("アップロードストリームからのレスポンス受信に失敗した: %v", err)
}
log.Printf("アップロードストリームのレスポンス: %s", res.Content)
```

**ユースケース:** ログファイル、IoT デバイスのメトリクス、動画ファイルの一部など、大規模なデータのアップロードに優れている。

---

### 4. 双方向ストリーミング RPC

**双方向ストリーミング RPC**は最も柔軟なモデルである。クライアントとサーバーの両方が、単一の gRPC 接続を介して独立してメッセージのストリームを相互に送信できる。読み取りと書き込みの順序は保証されず、アプリケーションのロジックに依存する。

#### サーバー側実装

サーバーハンドラは、読み取りと書き込みの両方に使用できるストリームを受け取る。いつでも`Recv()`でメッセージを読み取り、`Send()`でレスポンスを書き込むことが可能だ。

```go
// server/main.go
func (s *server) ChatStream(stream chat.ChatService_ChatStreamServer) error {
    for {
        in, err := stream.Recv()
        if err == io.EOF {
            return nil
        }
        if err != nil {
            return err
        }
        log.Printf("ChatStreamでメッセージ受信 from %s: %s", in.User, in.Content)

        // メッセージをエコーバックする
        if err := stream.Send(&chat.Message{User: "Server", Content: "Echo: " + in.Content}); err != nil {
            return err
        }
    }
}
```

#### クライアント側実装

クライアント側のロジックは、送受信を同時に処理する必要があるため、より複雑になる。一般的なパターンは、2 つの別々の goroutine を使用することだ。1 つはメッセージの送信、もう 1 つは受信を担当する。`sync.WaitGroup`などを使用して、調整と完了の通知を行う。

```go
// client/main.go
stream, err := c.ChatStream(context.Background()) // background contextを使用
if err != nil {
    log.Fatalf("チャットストリームを開けなかった: %v", err)
}

var wg sync.WaitGroup
wg.Add(2)

// メッセージ送信用のgoroutine
go func() {
    defer wg.Done()
    messages := []chat.Message{
        {User: "Marko", Content: "こんにちは！"},
        {User: "Marko", Content: "元気かい？"},
        {User: "Marko", Content: "双方向ストリームを使っている！"},
    }
    for _, msg := range messages {
        log.Printf("メッセージ送信: %s", msg.Content)
        if err := stream.Send(&msg); err != nil {
            log.Fatalf("メッセージの送信に失敗した: %v", err)
        }
        time.Sleep(time.Second)
    }
    stream.CloseSend() // 重要: ストリームの送信側を閉じる
}()

// メッセージ受信用のgoroutine
go func() {
    defer wg.Done()
    for {
        res, err := stream.Recv()
        if err == io.EOF {
            return // サーバーがストリームを閉じた
        }
        if err != nil {
            log.Fatalf("メッセージの受信に失敗した: %v", err)
        }
        log.Printf("サーバーからの受信: %s", res.Content)
    }
}()

wg.Wait()
log.Println("双方向ストリーム終了。")
```

**ユースケース:** リアルタイムのチャットサービス、共同ドキュメント編集、ライブゲームセッションなど、複雑でインタラクティブなアプリケーションの基盤となる。

---

### 結論

gRPC の 4 つの通信パターンをマスターすることで、正確なニーズに合わせた非常に効率的で専門的な API を構築する能力が手に入る。Unary RPC は多くの標準的なユースケースをカバーするが、ストリーミングパターンはリアルタイムのデータフロー、大規模なデータセット、そして完全にインタラクティブなサービスを処理する力を提供する。適切なパターンを選択することは、Go と gRPC で回復力とパフォーマンスに優れたマイクロサービスアーキテクチャを設計する上で重要なステップである。


gRPC の 4 つの通信パターン（Unary、サーバー ストリーミング、クライアント ストリーミング、双方向ストリーミング）のそれぞれを、Go で簡単なチャットサービスを実装しながら探求していく。

gRPC（Go）：コミュニケーションパターンの深掘り

Mastering gRPC in Go: A Deep Dive into Communication Patterns

Creating and publishing an NPM package can enhance your portfolio and allow you to share reusable code with the community. Recently I released [my own first package, a manga web reader](https://www.npmjs.com/package/mangatsu-reader) ([github.com/Mangatsu/mangatsu-reader](https://github.com/Mangatsu/mangatsu-reader)) that is still very much experimental. This guide will walk you through setting up a repository for a TypeScript project, as well as configuring the project with useful linting software, and finally how to build and publish your package to NPM.

#### Prerequisites

- npm v10.0.0+
- Internet connection

### Step 0: Choose your license

As for npm packages, usually MIT (or ISC) is recommended for the straightforwardness and ease of use. Sometimes, depending on the use case, Apache 2.0 with patent grant or strong copyleft license like (A)GPL 3.0 might fit your needs as well. Be sure to remember to create the `LICENSE` (or `COPYING`) file!

### Step 1: Setting up the NPM package

1. Initialize your NPM package: Start by creating a new directory for your project and navigating into it. Then initialize your project using `npm init`.
    ```bash
    mkdir name-of-the-package
    cd name-of-the-package
    npm init -y
    ```
    This will generate a `package.json` file with default configurations.
2. Initialize git with `git init` and create `.gitignore` file
3. Install TypeScript and related dependencies: To get started with TypeScript, you need to install TypeScript as well as some type definitions + rimraf for cleaning up
    ```bash
    npm install --save-dev typescript @types/node rimraf
    ```
4. Set up TypeScript configuration: Create a `tsconfig.json` file for your TypeScript configuration.
    ```json
    {
      "compilerOptions": {
        /* Language and Environment */
        "target": "ES2022",
        "lib": ["ES2022", "DOM", "DOM.Iterable"],
        "types": ["node", "react"],
        "jsx": "react",
        "useDefineForClassFields": true,
        /* Modules */
        "module": "ESNext",
        "moduleResolution": "bundler",
        "allowImportingTsExtensions": false,
        "resolveJsonModule": true,
        /* JavaScript Support */
        "allowJs": false,
        /* Emit */
        "declaration": true,
        "outDir": "./lib",
        "declarationDir": "./lib",
        /* Interop Constraints */
        "isolatedModules": true,
        "esModuleInterop": true,
        "forceConsistentCasingInFileNames": true,
        /* Type Checking */
        "strict": true,
        "noUnusedLocals": false,
        "noUnusedParameters": false,
        "noFallthroughCasesInSwitch": true,
        /* Completeness */
        "skipLibCheck": true
      },
      "include": ["src/**/*"],
      "exclude": ["node_modules", "lib"]
    }
    ```
    This setup ensures that TypeScript compiles source files from the `src` directory and outputs them into the `lib` directory.

### Step 2: Setting up linting (ESLint, Prettier, Husky)
1. Install dev dependencies:
    ```bash
    npm install --save-dev prettier eslint prettier-eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin
    ```
2. Create configuration files:
    `eslint.config.mjs`:
    ```json
    {
      "semi": false,
      "trailingComma": "all",
      "singleQuote": false,
      "tabWidth": 2,
      "useTabs": false,
      "printWidth": 120,
      "endOfLine": "lf"
    }
    ```

### (Optional) Setting up Husky pre-commit hook for automatic linting
1. Install Husky and lint-staged:
    ```bash
    npm install --save-dev husky lint-staged
    npx husky install
    ```
2. Configure lint-staged: Add a lint-staged configuration to run Prettier and ESLint on staged files before committing. In your package.json, add the following:
    ```json
    "lint-staged": {
      "*.{ts,tsx,js,jsx}": "eslint --cache --fix",
      "*.{ts,tsx,js,jsx,css,md}": "prettier --write"
    }
    ```
    ```json
    "scripts": {
      "prepare": "husky"
    }
    ```
3. Add pre-commit hook:
    ```bash
    echo "npx lint-staged" > .husky/pre-commit
    ```

### Step 3: Setting up the build process
1. Update the build script: Add a tsc, clean and build commands to your package.json using the TypeScript compiler (tsc).
    ```json
    "scripts": {
      "tsc": "tsc -p tsconfig.json",
      "clean": "rimraf lib && rimraf build",
      "build": "npm run clean && npm run tsc"
    }
    ```
    Running `npm run build` will compile your TypeScript files from src to the lib directory.
2. Copy assets after the build: If your package includes non-TypeScript files (e.g., images, JSON files, etc.), you can add a script to copy those assets to your lib folder. In package.json, add the following script:
    ```json
    "scripts": {
      "copy-assets": "node -e \"require('fs').cpSync('./src/assets', './lib/assets', {recursive: true});\"",
    }
    ```
3. Final build command
    ```json
    "scripts": {
      "build": "npm run clean && npm run tsc && npm run copy-assets"
    }
    ```

### Step 4: Publishing to package npm
1. Login to NPM: `npm login`
2. Update your package.json with metadata: Ensure your package.json has a valid name, version, description, main, license, and files field. The files field specifies which files are included in the package:
    ```json
    {
      "name": "name-of-the-package",
      "version": "0.1.0",
      "description": "",
      "main": "./lib/index.js",
      "types": "./lib/index.d.ts",
      "type": "module",
      "files": [
        "lib/"
      ],
      "repository": {
        "type": "git",
        "url": "github.com/<user,org>/<name-of-the-package>"
      },
      "keywords": [
        "typescript"
      ],
      "author": "Marko Kristian Leinikka",
      "license": "MIT"
    }
    ```
    3. Publish the package: `npm publish`. If it's your first time publishing, you can use `npm publish --access public` to make it publicly accessible.

### Conclusion

You've now created a TypeScript NPM package with linting, formatting, pre-commit hooks, and a build process that handles asset copying. Whether you're publishing utility functions or a full-fledged library, this setup will help ensure a smooth workflow and quality code.

By following this guide, you should now be able to confidently publish your TypeScript packages to NPM and manage a clean, maintainable codebase.

Learned how to build and publish an npm package

thumbnail_npm.png

npm.png

NPMパッケージを作って公開することで、ポートフォリオの強化もできて、便利なコードをコミュニティと共有できる。この間、自分の初めてのNPMパッケージを、[漫画ビューアー](https://www.npmjs.com/package/mangatsu-reader)（[github.com/Mangatsu/mangatsu-reader](https://github.com/Mangatsu/mangatsu-reader)）を、まだ完全にα版みたいなものではあるが、作って公開した。このガイドでは、TypeScriptプロジェクトのリポジトリをセットアップして、便利なリンティングツールを使う設定、最後にパッケージをNPMに公開する方法を説明するよ。

#### 前提条件

- npm v10.0.0以上
- ネット接続

### ステップ 0: ライセンスを選ぶ

npmパッケージの場合、MIT（またはISC）がシンプルで使いやすいからおすすめ。でも、使い方によってはApache 2.0（特許付き）や(A)GPL 3.0みたいな強力なコピーレフトライセンスが合うかも。`LICENSE`（もしくは`COPYING`）ファイルを作成するのを忘れないように！

### ステップ 1: NPMパッケージのセットアップ

1. **NPMパッケージの初期化**: プロジェクト用のディレクトリを作って移動してから、`npm init`でプロジェクトを初期化する。
    ```bash
    mkdir name-of-the-package
    cd name-of-the-package
    npm init -y
    ```
    これでデフォルト設定の `package.json` ファイルが生成される。
2. **gitの初期化**: `git init` でGitを初期化して、`.gitignore`ファイルを作成。
3. **TypeScriptと関連する依存パッケージのインストール**: TypeScriptや型定義、クリーンアップ用の `rimraf` をインストール。
    ```bash
    npm install --save-dev typescript @types/node rimraf
    ```
4. **TypeScript設定の作成**: `tsconfig.json`ファイルを作成して、TypeScriptの設定を行う。
    ```json
    {
      "compilerOptions": {
        "target": "ES2022",
        "lib": ["ES2022", "DOM", "DOM.Iterable"],
        "types": ["node", "react"],
        "jsx": "react",
        "useDefineForClassFields": true,
        "module": "ESNext",
        "moduleResolution": "bundler",
        "allowImportingTsExtensions": false,
        "resolveJsonModule": true,
        "allowJs": false,
        "declaration": true,
        "outDir": "./lib",
        "declarationDir": "./lib",
        "isolatedModules": true,
        "esModuleInterop": true,
        "forceConsistentCasingInFileNames": true,
        "strict": true,
        "noUnusedLocals": false,
        "noUnusedParameters": false,
        "noFallthroughCasesInSwitch": true,
        "skipLibCheck": true
      },
      "include": ["src/**/*"],
      "exclude": ["node_modules", "lib"]
    }
    ```
    この設定で、`src` ディレクトリからファイルをコンパイルして、`lib`ディレクトリに出力される。

### ステップ 2: リンティングの設定（ESLint、Prettier、Husky）

1. **開発依存パッケージのインストール**:
    ```bash
    npm install --save-dev prettier eslint prettier-eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin
    ```
2. **設定ファイルの作成**:
    `eslint.config.mjs`:
    ```json
    {
      "semi": false,
      "trailingComma": "all",
      "singleQuote": false,
      "tabWidth": 2,
      "useTabs": false,
      "printWidth": 120,
      "endOfLine": "lf"
    }
    ```

### （オプション） Huskyのプレコミットフックで自動リンティングを設定

1. **Huskyとlint-stagedのインストール**:
    ```bash
    npm install --save-dev husky lint-staged
    npx husky install
    ```
2. **lint-stagedの設定**: PrettierとESLintをコミット前に実行する設定を追加する。`package.json`に以下を追加。
    ```json
    "lint-staged": {
      "*.{ts,tsx,js,jsx}": "eslint --cache --fix",
      "*.{ts,tsx,js,jsx,css,md}": "prettier --write"
    }
    ```
    ```json
    "scripts": {
      "prepare": "husky"
    }
    ```
3. **プレコミットフックの追加**:
    ```bash
    echo "npx lint-staged" > .husky/pre-commit
    ```

### ステップ 3: ビルドプロセスの設定

1. **ビルドスクリプトの更新**: `package.json` に `tsc`, `clean`, `build` コマンドを追加。
    ```json
    "scripts": {
      "tsc": "tsc -p tsconfig.json",
      "clean": "rimraf lib && rimraf build",
      "build": "npm run clean && npm run tsc"
    }
    ```
    `npm run build` で `src` から `lib` ディレクトリにTypeScriptファイルがコンパイルされる。
2. **ビルド後にアセットをコピー**: パッケージに画像やJSONなどの非TypeScriptファイルが含まれている場合、次のスクリプトを追加してそれらを `lib` フォルダにコピーする。
    ```json
    "scripts": {
      "copy-assets": "node -e \"require('fs').cpSync('./src/assets', './lib/assets', {recursive: true});\"",
    }
    ```
3. **最終ビルドコマンド**:
    ```json
    "scripts": {
      "build": "npm run clean && npm run tsc && npm run copy-assets"
    }
    ```

### ステップ 4: npmパッケージの公開

1. **NPMにログイン**: `npm login`
2. **`package.json`のメタデータを更新**: `package.json`に、名前、バージョン、説明、メイン、ライセンス、ファイルフィールドを追加。ファイルフィールドでパッケージに含まれるファイルを指定する。
    ```json
    {
      "name": "name-of-the-package",
      "version": "0.1.0",
      "description": "",
      "main": "./lib/index.js",
      "types": "./lib/index.d.ts",
      "type": "module",
      "files": [
        "lib/"
      ],
      "repository": {
        "type": "git",
        "url": "github.com/<user,org>/<name-of-the-package>"
      },
      "keywords": [
        "typescript"
      ],
      "author": "Marko Kristian Leinikka",
      "license": "MIT"
    }
    ```
3. **パッケージを公開**: `npm publish`。初回公開時には `npm publish --access public` でパッケージを公開することができる。

### まとめ

これで、リンティング、フォーマット、プレコミットフック、アセットコピーを含むビルドプロセスを備えたTypeScript NPMパッケージが作成できた。ユーティリティ関数やライブラリを公開するとき、このセットアップがスムーズなワークフローと高品質なコードを維持するのに役立つ。

このガイドに沿って、TypeScriptパッケージをNPMに自信を持って公開し、綺麗でメンテナンスしやすいコードベースを管理できるようになるはず。


npmパッケージのビルドと公開のやり方を学ぼう

npmパッケージの公開方法

Publishing an npm package

When diving into modern authentication mechanisms, OAuth 2.0 stands out as one of the most widely adopted standards. I learned about key OAuth 2.0 authorization flow methods, each tailored to specific use cases. In this post, I'll walk through what I've learned about these methods, their purpose, and how they compare.

### 1. Authorization Code Grant

#### Explanation

The **Authorization Code Grant** is the most common OAuth 2.0 flow, designed for secure client-server communication. It is primarily used in web and native applications to exchange an authorization code for an access token.

1. **User Authentication**: The user authenticates with the authorization server.
2. **Authorization Code**: The client app receives an authorization code via a redirect URI after the user has authenticated.
3. **Token Exchange**: The client exchanges the authorization code for an access token by making a POST request to the authorization server.

This flow is secure because the access token is never exposed to the browser, and the authorization code is exchanged server-side.

<img width="750px" alt="Flow chart" src="https://strapi.kohana.fi/uploads/authcode_grant_9f937990d6.png" />

```json
POST /token HTTP/1.1
Host: auth.example.com
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "<authorization_code>",
  "client_id": "<client-id>",
  "client_secret": "<client-secret>",
  "redirect_uri": "https://example.com/callback"
}
```

#### 2. Authorization Code Grant with PKCE

The **Authorization Code Grant** is very similar to the original Authorization Code Grant with one exception: To address the security vulnerabilities in public clients (like mobile apps or single-page apps), OAuth 2.0 introduced **Proof Key for Code Exchange (PKCE)**. This adds an extra layer of security, ensuring that the client that initiates the request is the one that can exchange the authorization code for the access token.

1. **Code Verifier & Code Challenge**: The client generates a random string (code verifier) and hashes it to create a code challenge.
2. **Authorization Request**: The client sends the code challenge during the authorization request.
3. **Token Exchange**: The client sends the code verifier along with the authorization code to exchange for an access token.

<img width="750px" alt="Flow chart" src="https://strapi.kohana.fi/uploads/pkce_grant_34699dda1e.png" />

```json
POST /token HTTP/1.1
Host: auth.example.com
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "<authorization_code>",
  "client_id": "<client-id>",
  "code_verifier": "<code_verifier>",
  "redirect_uri": "https://example.com/callback"
}
```

```typescript
// Helper function to generate a code challenge from the verifier
async function generateCodeChallenge(verifier: string) {
  // Encodes the verifier
  const encoder = new TextEncoder()
  const data = encoder.encode(verifier)

  // Hashes the encoded verifier
  const hashBuffer = await crypto.subtle.digest("SHA-256", data)
  const hashArray = Array.from(new Uint8Array(hashBuffer))

  // Encodes the hash as base64
  const base64String = btoa(String.fromCharCode.apply(null, hashArray))

  // Converts the base64 string to a URL safe string
  return base64String.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "")
}
```

#### 3. Implicit Grant (deprecated)

The **Implicit Grant** was designed for client-side applications like Single Page Applications (SPAs). However, this grant type is now deprecated due to its security vulnerabilities. It exposes access tokens directly in the URL fragment, which could be intercepted by malicious actors.

1. Client requests an access token directly from the authorization server.
2. The access token is returned in the URL fragment, which is visible to the client and potentially exposed to malicious actors.

Because of the exposed access tokens in URL can lead to potential security risks, **instead, Authorization Code Grant with PKCE** is now the recommended flow for client-side apps.

<img width="750px" alt="Flow chart" src="https://strapi.kohana.fi/uploads/implicit_grant_5fc1451fdc.png" />

#### 4. Client Credentials Grant

The **Client Credentials Grant** is for machine-to-machine communication. In this flow, the client application authenticates with its own credentials (client ID and secret) to obtain an access token, typically for accessing its own resources or a third-party API.

1. **Client** authenticates with the authorization server using its client ID and secret.
2. **Authorization server** issues an access token to the client.
3. **Client** uses the access token to access protected resources.

<img width="750px" alt="Flow chart" src="https://strapi.kohana.fi/uploads/clientcredentials_grant_d755b2d7b6.png" />

```json
POST /token HTTP/1.1
Host: auth.example.com
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "<client-id>",
  "client_secret": "<client-secret>"
}
```

#### 5. Extension Grant

The **Extension Grant** is a custom grant type used for special use cases that don't fit into standard OAuth 2.0 flows. For example, the **Device Authorization Grant** (RFC 8628) allows devices with limited input capabilities (like smart home devices) to request authorization through a secondary device, like a smartphone.

1. **Device** requests authorization from the server.
2. **User** completes the authorization on a separate device (e.g., smartphone).
3. **Device** is issued an access token after user approval.

<img width="750px" alt="Flow chart" src="https://strapi.kohana.fi/uploads/extension_grant_8b856c526c.png" />

#### Conclusion

Learning about these different OAuth 2.0 authorization methods has been an eye-opener in understanding both security concerns and proper implementations for different scenarios. While the Authorization Code Grant with PKCE is the recommended choice for public apps due to its enhanced security, especially for mobile and single-page applications, other flows like Client Credentials Grant and Extension Grants are vital for machine-to-machine and custom use cases.

The Authorization Code Grant stands out as the most flexible and widely applicable, especially in situations where user interaction is needed. Its ability to securely exchange an authorization code for an access token without exposing sensitive credentials in the front-end has made it the standard for web-based authentication. The addition of PKCE ensures that even public clients, which cannot protect client secrets, can maintain a high level of security. This makes PKCE an essential feature in any modern web or mobile app that involves sensitive user data.

On the other hand, the Client Credentials Grant is fundamental in server-to-server communication, where no user is involved. It’s particularly useful for backend services that need to authenticate with APIs or microservices. By utilizing machine-to-machine communication, this grant type ensures that systems can securely interact without user intervention, enabling seamless automation in many cloud or enterprise-level architectures.

For use cases where standard grants do not suffice, the Extension Grants provide the flexibility needed to build custom authentication flows. This includes scenarios like the Device Authorization Grant, which is particularly beneficial for IoT devices and smart devices like wearables, TVs, and other appliances with limited input capabilities. Such grants show how OAuth 2.0 can be adapted to fit evolving technological needs and non-traditional client environments.

Understanding these flows is essential when designing secure, scalable, and flexible authentication systems. Each flow serves a specific use case, and leveraging the right grant type can dramatically reduce security risks while improving the user experience. In the context of a rapidly evolving digital landscape, OAuth 2.0 provides a robust and standardized approach to managing access across diverse systems and devices, making it the go-to framework for modern identity management.

Finally, the OAuth 2.0 framework continues to evolve with industry needs, and knowing when and how to use each flow helps developers and system architects stay ahead of security threats. Implementing the right authorization method not only protects user data but also helps maintain the integrity of the systems in which these methods are deployed.

I learned about the key OAuth 2.0 authorization flow methods

large_oauth2.jpg

medium_oauth2.jpg

small_oauth2.jpg

thumbnail_oauth2.jpg

oauth2.jpg

OAuth 2.0は、現代の認証メカニズムの中で最も広く採用されている標準の一つ。特に、異なるユースケースに合わせた複数の認証フローが存在することを学んだ。このポストでは、それぞれのフローの役割や目的、そしてどういった違いがあるかを見ていく。

### 1. 認可コードグラント

#### 説明

**Authorization Code Grant** は、最も一般的なOAuth 2.0のフローで、クライアントとサーバー間の安全な通信のために設計されている。主にウェブやネイティブアプリで、認証コードをアクセストークンに交換するために使われる。

1. **ユーザー認証**: ユーザーが認証サーバーで認証を行う。
2. **認可コード**: 認証が完了した後、リダイレクトURIを通してクライアントアプリが認可コードを受け取る。
3. **トークン交換**: クライアントがPOSTリクエストを認証サーバーに送り、認可コードをアクセストークンに交換する。

このフローは、アクセストークンがブラウザに公開されることがなく、認可コードはサーバー側で安全に処理されるため、セキュリティが保たれる。

<img width="750px" alt="Flow chart" src="https://strapi.kohana.fi/uploads/authcode_grant_9f937990d6.png" />

```json
POST /token HTTP/1.1
Host: auth.example.com
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "<authorization_code>",
  "client_id": "<client-id>",
  "client_secret": "<client-secret>",
  "redirect_uri": "https://example.com/callback"
}
```

### 2. PKCE付き認可コードグラント

**Authorization Code Grant with PKCE**は認可コードグラント（Authorization Code Grant）とほぼ同じ流れとなっている。唯一の差は、公開クライアント（モバイルアプリやシングルページアプリなど）のセキュリティリスクに対処するためにOAuth 2.0で 導入された**PKCE (Proof Key for Code Exchange)** がフローのステップになっているということ。これにより、リクエストを行ったクライアントだけが認可コードをアクセストークンに交換できるようにする追加のセキュリティが提供される。

1. **コードベリファイア & コードチャレンジ**: クライアントがランダムな文字列（コードベリファイア）を生成し、それをハッシュ化してコードチャレンジを作成する。
2. **認可リクエスト**: クライアントが認可リクエスト中にコードチャレンジを送信する。
3. **トークン交換**: クライアントが認可コードと共にコードベリファイアを送信し、アクセストークンを取得する。

<img width="750px" alt="Flow chart" src="https://strapi.kohana.fi/uploads/pkce_grant_34699dda1e.png" />

```json
POST /token HTTP/1.1
Host: auth.example.com
Content-Type: application/json

{
  "grant_type": "authorization_code",
  "code": "<authorization_code>",
  "client_id": "<client-id>",
  "code_verifier": "<code_verifier>",
  "redirect_uri": "https://example.com/callback"
}
```

```typescript
// Helper function to generate a code challenge from the verifier
async function generateCodeChallenge(verifier: string) {
  // Encodes the verifier
  const encoder = new TextEncoder()
  const data = encoder.encode(verifier)

  // Hashes the encoded verifier
  const hashBuffer = await crypto.subtle.digest("SHA-256", data)
  const hashArray = Array.from(new Uint8Array(hashBuffer))

  // Encodes the hash as base64
  const base64String = btoa(String.fromCharCode.apply(null, hashArray))

  // Converts the base64 string to a URL safe string
  return base64String.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "")
}
```

### 3. インプリシットグラント（非推奨）

**Implicit Grant** は、クライアントサイドのアプリ（例えばシングルページアプリケーション）向けに設計されたもの。しかし、セキュリティの問題があるため、現在は非推奨となっている。このフローでは、アクセストークンがURLフラグメントに直接露出するため、悪意のある第三者にインターセプトされる可能性がある。

1. クライアントが直接認証サーバーからアクセストークンをリクエスト。
2. アクセストークンがURLフラグメント内で返され、これがクライアントに表示されるため、潜在的に危険。

アクセストークンがURLに露出してしまうとセキュリティリスクが高まるため、**PKCE付き認可コードグラント**がクライアントサイドアプリ向けの推奨フローとなっている。

<img width="750px" alt="Flow chart" src="https://strapi.kohana.fi/uploads/implicit_grant_5fc1451fdc.png" />

### 4. クライアントクレデンシャルグラント

**Client Credentials Grant** は、マシン間通信用のフロー。クライアントアプリケーションが自身のクレデンシャル（クライアントIDとシークレット）を使って認証サーバーに認証を行い、アクセストークンを取得する。主に自分のリソースやサードパーティのAPIにアクセスするために使われる。

1. **クライアント** がクライアントIDとシークレットを使って認証サーバーに認証を行う。
2. **認証サーバー** がクライアントにアクセストークンを発行。
3. **クライアント** がアクセストークンを使って保護されたリソースにアクセスする。

<img width="750px" alt="Flow chart" src="https://strapi.kohana.fi/uploads/clientcredentials_grant_d755b2d7b6.png" />

```json
POST /token HTTP/1.1
Host: auth.example.com
Content-Type: application/json

{
  "grant_type": "client_credentials",
  "client_id": "<client-id>",
  "client_secret": "<client-secret>"
}
```

### 5. エクステンショングラント

**Extension Grant** は、標準のOAuth 2.0フローに適合しない特定のユースケースに対応するためのカスタムグラントタイプ。例えば、**デバイス認証グラント (Device Authorization Grant)** は、スマートホームデバイスなど入力が限られたデバイスが、スマートフォンなどのセカンダリデバイスを使って認証を行うために利用される。

1. **デバイス** がサーバーに認証リクエストを送信。
2. **ユーザー** が別のデバイス（例: スマートフォン）で認証を完了。
3. **デバイス** はユーザー承認後にアクセストークンを受け取る。

<img width="750px" alt="Flow chart" src="https://strapi.kohana.fi/uploads/extension_grant_8b856c526c.png" />

### さいごに

これらのOAuth 2.0認証フローを学ぶことで、さまざまなシナリオにおけるセキュリティの懸念や、適切な実装方法を理解することができた。モバイルアプリやシングルページアプリ向けには、PKCE付きの認可コードグラントが推奨されるが、サーバー間通信やカスタムユースケースでは、**Client Credentials Grant** や **Extension Grant** などのフローが重要になる。

特に、**Authorization Code Grant** は柔軟性が高く、ユーザーの関与が必要なシチュエーションに最も適している。フロントエンドに機密情報を露出させることなく、認可コードを安全にアクセストークンに交換できる点が、このフローの最大の利点だ。PKCEを追加することで、クライアントシークレットを保護できない公開クライアントでも高いセキュリティレベルを維持できる。

一方、**Client Credentials Grant** は、ユーザーが関与しないサーバー間通信に不可欠だ。特にバックエンドサービスがAPIやマイクロサービスに認証する必要がある場合に便利で、マシン間での自動化をサポートする。

また、標準的なグラントでは対応できないユースケースには、**Extension Grant** が柔軟な認証フローを提供する。IoTデバイスやスマートデバイス向けの **Device Authorization Grant** はその良い例で、入力が制限されたデバイスに最適だ。こうした拡張グラントにより、OAuth 2.0は進化するテクノロジーや非伝統的なクライアント環境にも対応できる。

これらのフローを理解することは、セキュアで拡張可能な認証システムを設計する際に非常に重要だ。それぞれのフローには特定のユースケースがあり、適切なグラントタイプを活用することで、セキュリティリスクを大幅に減らし、ユーザーエクスペリエンスを向上させることができる。急速に進化するデジタル環境において、OAuth 2.0は多様なシステムやデバイス間でアクセスを管理するための堅牢で標準化されたアプローチを提供し、現代のアイデンティティ管理において欠かせないフレームワークとなっている。

最後に、OAuth 2.0は業界のニーズに合わせて進化を続けており、それぞれのフローをいつ、どのように使うべきかを理解することで、開発者やシステムアーキテクトはセキュリティ脅威に先んじて対処することができる。適切な認証方法を実装することは、ユーザーデータを保護するだけでなく、システム全体の健全性を維持するためにも重要だ。


OAuth 2.0の認証フローに関して理科してみた

OAuth 2.0 認証フローを理解してみた

Understanding OAuth 2.0 Authorization Methods

### Introduction

Kubernetes has become one of the most important tools in the DevOps world, offering powerful orchestration for containerized applications. After completing the [DevOps with Kubernetes](https://devopswithkubernetes.com) course, I now have a much clearer understanding of how Kubernetes works and how it can be used to manage software at scale. This course was a great starting point, introducing me to essential Kubernetes concepts, including microservice architecture, automated deployment, and scaling. Here’s my report on what I learned, what Kubernetes is, and how this powerful software can transform the way we develop and manage applications.

### What is Kubernetes?

Kubernetes (often abbreviated as K8s) is an open-source container orchestration platform designed to automate the deployment, scaling, and management of containerized applications. Developed by Google, it has since become the de facto standard for managing cloud-native applications.

In essence, Kubernetes simplifies the complex process of managing application containers across multiple environments. It ensures that your applications run smoothly by automating deployment, scaling, and operations. Whether you're working with a small cluster or managing applications that span multiple cloud environments, Kubernetes is built to handle it all.

### Course Breakdown: From Fundamentals to Advanced Concepts

The **"DevOps with Kubernetes"** course is divided into five parts, each focusing on different aspects of Kubernetes, from initial deployment to advanced techniques like service mesh and GitOps. Here's a breakdown of each section and what I learned:

#### Part 1: Getting Started with Kubernetes

The first part introduced me to Kubernetes with **K3s**. Here, I learned the basics:

- **First Deployment:** I was guided through my first Kubernetes deployment, learning how to deploy containerized applications in a cluster.
- **Debugging:** Introduction to debugging tools to identify issues within Kubernetes.
- **Networking and Storage:** Understanding how networking works between pods and managing persistent storage for applications.
  
This section provided a solid foundation, giving me a clear view of how Kubernetes orchestrates applications across nodes in a cluster.

#### Part 2: Networking and Cluster Management

Part two delved deeper into Kubernetes networking and cluster organization:

- **Networking between Pods:** I learned how Kubernetes manages communication between different services running inside the cluster. This covered setting up service discovery and managing pod-to-pod communication.
- **Cluster Organization:** This section focused on structuring clusters for better scalability and reliability, which is crucial as your application grows.
- **StatefulSets and Jobs:** I also learned about **StatefulSets**, which are essential when you need stable, persistent data and **Jobs** for running batch processes.

These concepts are fundamental to managing microservices that need reliable networking and persistent data.

#### Part 3: Working with Google Kubernetes Engine (GKE)

Part three was all about the Google Kubernetes Engine:

- **GKE Features:** We explored how to deploy and manage Kubernetes clusters on GKE, taking advantage of the cloud-native features that GKE offers, such as managed scaling and built-in monitoring.
- **Deployment Pipeline:** I learned about building a **CI/CD pipeline** that integrates with GKE, automating the deployment process for faster development cycles.

This section showcased Kubernetes' power in a cloud-native environment, demonstrating how GKE simplifies scaling and managing production-grade applications.

#### Part 4: Advanced Kubernetes Techniques

The fourth section introduced more advanced Kubernetes features:

- **Update Strategies and Monitoring:** I learned about rolling updates and canary deployments to minimize downtime during updates. **Prometheus** was introduced as a monitoring tool to ensure applications are healthy.
- **GitOps:** This was an interesting concept, which integrates **git** as a single source of truth for application infrastructure, streamlining deployments and infrastructure management.
- **Messaging Systems:** We also touched on integrating messaging systems like NATS, which is essential for distributed applications.

This section helped me understand how Kubernetes can handle sophisticated update strategies and how GitOps integrates with infrastructure as code.

#### Part 5: Kubernetes Internals and Beyond

The final part took a deep dive into the internals of Kubernetes:

- **Kubernetes Internals:** Here, I gained insights into how Kubernetes works under the hood. Understanding its internal architecture gave me a much deeper appreciation of its power and flexibility.
- **Custom Resource Definitions (CRDs):** CRDs allow developers to extend Kubernetes' functionality by defining custom resources, opening the door to highly specialized workloads.
- **Service Mesh and Beyond:** Finally, we explored **Service Mesh** technologies, like Istio, which manage the communication between services in a more secure and observable way.

This part was the most advanced, focusing on how Kubernetes can be extended and optimized for specific use cases. It also looked at Kubernetes' future and how it is evolving to meet the needs of modern software development.

### What Makes Kubernetes Powerful?

Through this course, I realized that Kubernetes is much more than just a tool for deploying containers. It’s a platform for managing the entire lifecycle of containerized applications. A few key takeaways:

- **Scalability:** Kubernetes automates scaling, ensuring applications can handle increased load without manual intervention.
- **Resilience:** Built-in features like **self-healing**, **auto-scaling**, and **load balancing** mean that Kubernetes keeps applications running smoothly, even when individual components fail.
- **Flexibility:** From running a simple containerized app on a local machine using K3s to managing complex multi-cloud deployments with GKE, Kubernetes handles it all.

### Conclusion

Completing the "DevOps with Kubernetes" course gave me a strong foundation in using Kubernetes to manage modern software architectures. I learned how Kubernetes automates the complexities of deploying, scaling, and managing applications, making it an essential tool for any DevOps workflow. Whether working with a small team or deploying at a global scale, Kubernetes simplifies the process and offers robust tools to manage applications efficiently.

Kubernetes is an incredibly powerful piece of software, and I’m excited to continue exploring its potential, especially in larger, more complex environments. This course has not only demystified Kubernetes for me but has also shown how it can transform software development and deployment.

If you're looking to understand how to develop, manage, and scale microservices, I highly recommend starting with Kubernetes and this introductory course.


kubernetes-1.svg

### はじめに

Kubernetesは、コンテナ化されたアプリケーションを強力にオーケストレーションしてくれる今やDevOpsの世界で最も重要なツールの一つになっていてる。最近、「[DevOps with Kubernetes](https://devopswithkubernetes.com)」というコースを受講したことで、Kubernetesがどのように動作し、ソフトウェアをスケールして管理するのにどう活用できるかが、よりクリアに分かるようになった。このコースは、マイクロサービスアーキテクチャ、デプロイの自動化、スケーリングといったKubernetesの基本概念を学ぶには最適なスタート地点だった。ここでは、学んだこと、Kubernetesが何なのか、そしてこの強力なソフトウェアが開発・運用の方法をどう変えるかについてまとめてみた。

### Kubernetesとは？

Kubernetes（K8sと略されることもある）は、オープンソースのコンテナオーケストレーションプラットフォームで、コンテナ化されたアプリケーションのデプロイ、スケーリング、管理を自動化するように設計されている。Googleによって開発され、今ではクラウドネイティブアプリケーションを管理するデファクトスタンダードとなっている。

要するに、Kubernetesは複数の環境にわたるアプリケーションコンテナの管理をシンプルにしてくれる。アプリケーションのデプロイやスケーリング、運用を自動化することで、スムーズに動作させることができるんだ。小規模なクラスタであれ、複数のクラウド環境にまたがるアプリケーションであれ、Kubernetesはそれをすべて扱えるように作られている。

### コースの概要：基礎から応用まで

**「DevOps with Kubernetes」** コースは5つのパートに分かれていて、それぞれKubernetesの異なる側面に焦点を当てている。最初のデプロイから、サービスメッシュやGitOpsのような高度なテクニックまでカバーされている。各セクションで学んだことを以下にまとめてみた。

#### パート1：Kubernetesの基礎

最初のパートでは、**K3s**を使ってKubernetesの基本に取り組んだ。ここでは次のようなことを学んだ：

- **初めてのデプロイ:** 初めてKubernetesのデプロイを行い、クラスタ内にコンテナ化されたアプリケーションをデプロイする方法を学んだ。
- **デバッグ:** Kubernetes内で発生する問題を特定するためのデバッグツールについての導入。
- **ネットワーキングとストレージ:** Pod間のネットワークの仕組みと、アプリケーションのための永続的なストレージの管理方法を理解。

このセクションは、Kubernetesがノード間でアプリケーションをどのようにオーケストレーションしているのか、明確な理解を得るための基礎を築いてくれた。

#### パート2：ネットワークとクラスタ管理

パート2では、Kubernetesのネットワークとクラスタの管理にさらに深く掘り下げた：

- **Pod間のネットワーキング:** Kubernetesがクラスタ内で実行されているさまざまなサービス間の通信をどのように管理しているのかを学んだ。サービスディスカバリーの設定やPod間の通信の管理についても触れた。
- **クラスタの構成:** アプリケーションの成長に伴って、スケーラビリティと信頼性を確保するためのクラスタの構成に関する内容。
- **StatefulSetsとJobs:** 永続的なデータを必要とする場合に重要な**StatefulSets**や、バッチ処理を実行するための**Jobs**についても学んだ。

これらの概念は、信頼性の高いネットワーキングや永続的なデータを必要とするマイクロサービスを管理するために不可欠なものだ。

#### パート3：Google Kubernetes Engine（GKE）を使った作業

パート3では、Google Kubernetes Engineについて学んだ：

- **GKEの特徴:** GKEでKubernetesクラスタをデプロイして管理する方法を探り、スケーリングや組み込みのモニタリングなど、GKEのクラウドネイティブな機能を活用した。
- **デプロイパイプライン:** **CI/CDパイプライン**を構築し、GKEと統合して、より迅速な開発サイクルのためにデプロイプロセスを自動化する方法を学んだ。

このセクションでは、クラウドネイティブ環境でのKubernetesの力を実感でき、GKEがどのようにしてプロダクション向けアプリケーションのスケーリングと管理を簡素化しているのかがよくわかった。

#### パート4：高度なKubernetes技術

パート4では、さらに高度なKubernetesの機能について学んだ：

- **アップデート戦略とモニタリング:** ローリングアップデートやカナリアデプロイによって、ダウンタイムを最小限に抑えながらアップデートを行う方法を学んだ。**Prometheus**を使ったアプリケーションのモニタリングも導入された。
- **GitOps:** アプリケーションのインフラ管理のシングルソースとして**Git**を使い、デプロイやインフラの管理を効率化するGitOpsの概念はとても興味深かった。
- **メッセージングシステム:** また、分散アプリケーションに不可欠なNATSのようなメッセージングシステムの統合についても触れた。

このセクションでは、Kubernetesが高度なアップデート戦略をどのように処理し、GitOpsがインフラ管理にどのように組み込まれているかを理解することができた。

#### パート5：Kubernetesの内部とその先

最終パートでは、Kubernetesの内部について深く掘り下げた：

- **Kubernetesの内部:** Kubernetesが内部でどのように動作しているのかについての洞察を得た。内部アーキテクチャを理解することで、その力と柔軟性に対する理解が深まった。
- **カスタムリソース定義（CRD）:** CRDを使うことで、開発者はKubernetesの機能を拡張し、特化したワークロードを扱うためのカスタムリソースを定義できる。
- **サービスメッシュとその先:** 最後に、**Istio**のようなサービスメッシュ技術を探り、サービス間の通信をより安全で観測可能に管理する方法を学んだ。

このパートは最も高度で、Kubernetesを特定のユースケースに合わせて拡張し、最適化する方法に焦点を当てていた。また、Kubernetesの将来と、モダンなソフトウェア開発のニーズにどのように対応していくのかも考察された。

### Kubernetesの強力な点は？

このコースを通じて、Kubernetesは単なるコンテナデプロイツールではなく、コンテナ化されたアプリケーションのライフサイクル全体を管理するプラットフォームだと気づいた。いくつかの重要なポイントをまとめると：

- **スケーラビリティ:** Kubernetesはスケーリングを自動化し、アプリケーションが負荷の増加に対応できるようにする。
- **レジリエンス:** **セルフヒーリング**、**オートスケーリング**、**ロードバランシング**などの機能により、Kubernetesは個々のコンポーネントが失敗しても、アプリケーションがスムーズに動作し続けるようにする。
- **柔軟性:** K3sを使ってローカルマシンでシンプルなコンテナアプリを動かすところから、GKEを使った複雑なマルチクラウドのデプロイメント管理まで、Kubernetesはすべてを扱える柔軟性を持っている。

### 結論

「DevOps with Kubernetes」コースを修了したことで、Kubernetesを使ってモダンなソフトウェアアーキテクチャを管理するための強力な基盤ができた。Kubernetesが、デプロイやスケーリング、アプリケーション管理の複雑さを自動化する方法を学び、DevOpsのワークフローに不可欠なツールであることを実感した。小さなチームで作業する場合でも、グローバル規模でのデプロイメントを行う場合でも、Kubernetesはプロセスをシンプルにし、アプリケーションを効率的に管理するための強力なツールを提供してくれる。

Kubernetesは非常に強力なソフトウェアであり、特に大規模で複雑な環境での可能性を探るのが楽しみだ。このコースを通じて、Kubernetesの仕組みが解明されただけでなく、ソフトウェアの開発とデプロイメントの方法がどのように変わるかも理解できた。

マイクロサービスの開発、管理、スケーリングを理解したいなら、Kubernetesとこの入門コースを始めるのを強くおすすめしたい。


「DevOps with Kubernetes」というコースを受講したことで、Kubernetesがどのように動作し、ソフトウェアをスケールして管理するのにどう活用できるかをここでブロク化したみた。

Kubernetsを学んでみた

Learning Kubernets

### Introduction

In the ever-evolving landscape of web development, choosing the right framework can significantly impact project's success. Recently, I delved into the world of Svelte and SvelteKit through their official documentation and coursework, exploring their features, benefits, and unique selling points. In this post, I’ll share my insights on Svelte and how they compare to other popular combinations like Nuxt.js & Vue and Next.js & React.

### Understanding Svelte

#### Svelte: a brief overview

Svelte is a modern JavaScript framework designed to create efficient web applications with minimal boilerplate. Unlike other frameworks such as React or Vue, Svelte shifts much of the work to compile time, resulting in faster runtime performance and smaller bundle sizes.

#### Key features of Svelte

- **Compile time optimization:** Svelte compiles your components into efficient imperative code, minimizing the need for a virtual DOM.
- **Reactivity:** Svelte's reactivity model is simple and intuitive, allowing developers to create responsive applications with ease.
- **Scoped styles:** Svelte components come with scoped styles by default, ensuring your styles don’t leak into other parts of your application.

### SvelteKit: the full-stack framework

SvelteKit is the official framework for building web applications with Svelte. It provides a complete toolkit for creating scalable and performant web applications, offering features like server-side rendering (SSR) and static site generation (SSG).

#### Key features of svelteKit

- **Server-Side Rendering (SSR):** Enhance performance and SEO by rendering pages on the server.
- **Static Site Generation (SSG):** Generate static assets for faster load times and better scalability.
- **File-based routing:** Simplify navigation and routing with a file-based approach.
- **Integrated tooling:** Built-in support for TypeScript, SCSS, and more.

### Comparing SvelteKit to Vue+Nuxt and Next.js (React)

#### Vue and Nuxt.js

Vue.js is a progressive JavaScript framework for building user interfaces. It is known for its simplicity and flexibility, making it a favorite among developers for creating interactive web applications.

Nuxt.js is a framework built on top of Vue.js that provides a robust solution for server-side rendering, static site generation, and other advanced features.

##### Key Differences

- **Learning curve:** Vue has a gentle learning curve, making it accessible to beginners. Svelte is also beginner-friendly but takes a different approach with its compile-time optimizations.
- **Performance:** Svelte's compile-time optimization often results in better runtime performance compared to Vue's virtual DOM.
- **Tooling:** Nuxt.js offers a rich ecosystem and extensive documentation, while SvelteKit, although powerful, is relatively newer with less community support and still growing.

#### React and Next.js

React is a widely-used JavaScript library for building user interfaces, known for its component-based architecture and vast ecosystem.

In turn, Next.js is a framework for React that also provides server-side rendering, static site generation, and many other features out of the box.

#### Key Differences

- **Rendering:** Both SvelteKit and Next.js offer SSR and SSG, but Svelte's approach eliminates the virtual DOM, potentially offering better performance.
- **Developer experience:** React's ecosystem is mature and extensive, while Svelte’s syntax and reactivity model provide a refreshing and simpler alternative.
- **Community and ecosystem:** React and Next.js have a larger community and more third-party integrations compared to the relatively new SvelteKit.

### Conclusion

Svelte (SvelteKit) brings a unique perspective to web development, offering impressive performance benefits and a modern approach to building web applications. While Vue (Nuxt.js) and React (Next.js) are established and robust solutions with extensive ecosystems, Svelte stands out with its compile-time optimizations and simplicity.

#### Use cases: Svelte (SvelteKit)

- **Single-Page Applications (SPAs):** SvelteKit’s built-in support for client-side routing, along with its minimal bundle size and fast performance, makes it an excellent choice for SPAs that need to load quickly and provide a smooth user experience.
  
- **Small to medium projects:** Svelte’s simplicity and lack of boilerplate code make it ideal for smaller teams or solo developers working on projects where development speed and maintainability are key.

- **Static Site Generation (SSG):** With SvelteKit's ability to generate static sites, it's perfect for blogs, marketing sites, and documentation platforms where content is mostly static but benefits from occasional dynamic features.

- **Highly interactive web applications:** Svelte’s reactivity model is perfect for applications requiring complex user interactions with minimal latency, such as data dashboards, real-time collaborative tools, and interactive storytelling platforms.

#### Use cases: Vue (Nuxt.js)

- **Progressive Web Applications (PWAs):** Vue's gentle learning curve combined with Nuxt.js's powerful features make it a great choice for developing PWAs that need to provide an app-like experience on the web.

- **Large-scale enterprise applications:** Vue’s flexibility and Nuxt.js's capabilities in handling server-side rendering, along with a strong ecosystem of plugins and tools, make it suitable for large-scale applications with complex routing and state management needs.

- **E-commerce platforms:** The modular nature of Vue and Nuxt.js, along with robust state management solutions like Vuex, make them ideal for building feature-rich e-commerce platforms that require SEO optimization and fast, reliable performance.

#### Use cases: React (Next.js)

- **Universal applications:** Next.js excels at building universal (isomorphic) applications that render on both the server and the client, making it ideal for content-heavy websites, news portals, and applications requiring SEO.

- **Complex web applications:** React’s extensive ecosystem, combined with Next.js’s server-side rendering and API routes, makes it a strong candidate for complex applications with high interactivity, like social media platforms, online learning tools, and content management systems.

- **Microservices and API-driven architectures:** With Next.js, it’s easy to integrate with various backend services and APIs, making it suitable for projects that need to consume and manage data from multiple sources.

- **Rich user interfaces:** React's component model and vast library support make it ideal for applications where a sophisticated UI is essential, such as design tools, media-rich websites, and interactive data visualizations.

### Final thoughts

Choosing the right framework depends on your specific project requirements and personal preferences. Svelte and SvelteKit are excellent choices for projects that prioritize performance, simplicity, and modern development practices. Vue and Nuxt.js provide a balance of flexibility and ease of use, making them great for a wide range of applications. React and Next.js, with their robust ecosystem and versatility, are well-suited for complex and large-scale projects.

By understanding the key features and differences between these frameworks, you can make an informed decision and leverage the best tools for your web development projects.


Recently, I delved into the world of Svelte and SvelteKit through their official documentation and coursework, exploring their features, benefits, and unique selling points. In this post, I’ll share my insights on Svelte and how they compare to other popular combinations like Nuxt.js & Vue and Next.js & React.

medium_svelte.png

small_svelte.png

thumbnail_svelte.png

svelte.png

### はじめに

ウェブ開発の世界は常に進化していて、どのフレームワークを選ぶかがプロジェクトの成功に大きく影響する。SvelteとSvelteKitの公式ドキュメントやコースを通じて、それらの特徴や利点、ユニークなポイントを探ってみた。この投稿では、Svelteについてのインサイトと、Vue（Nuxt.js）、React（Next.js）といった他の人気のあるフレームワークと比較した内容を共有する。

### Svelte

#### Svelteの概要

Svelteは、最小限のボイラープレートで効率的なウェブアプリケーションを作成するために設計されたモダンなJavaScriptフレームワーク。他のフレームワーク、例えばReactやVueとは異なり、Svelteは多くの処理をコンパイル時に行うため、実行時のパフォーマンスが向上し、バンドルサイズも小さくなる。

#### Svelteの主な特徴

- **コンパイル時の最適化:** Svelteはコンポーネントを効率的な命令型コードにコンパイルし、仮想DOMの必要性を最小限に抑える。
- **リアクティビティ:** Svelteのリアクティブモデルはシンプルで直感的であり、開発者が簡単にレスポンシブなアプリケーションを作成できる。
- **スコープされたスタイル:** Svelteのコンポーネントにはデフォルトでスコープされたスタイルが含まれており、スタイルが他の部分に漏れないようにしている。

### SvelteKit: フルスタックフレームワーク

SvelteKitは、Svelteを使ってウェブアプリケーションを構築するための公式フレームワーク。スケーラブルでパフォーマンスの高いウェブアプリケーションを作成するための完全なツールキットを提供し、サーバーサイドレンダリング（SSR）や静的サイト生成（SSG）などの機能を備えている。

#### SvelteKitの主な特徴

- **サーバーサイドレンダリング（SSR）:** サーバーでページをレンダリングすることで、パフォーマンスとSEOを向上させる。
- **静的サイト生成（SSG）:** より速い読み込み時間とスケーラビリティを実現するために、静的アセットを生成する。
- **ファイルベースのルーティング:** ファイルベースのアプローチでナビゲーションとルーティングを簡素化する。
- **統合されたツール:** TypeScript、SCSSなどのサポートが組み込まれている。

### SvelteKitとVue+NuxtおよびNext.js（React）の比較

#### VueとNuxt.js

Vue.jsは、ユーザーインターフェースを構築するためのプログレッシブなJavaScriptフレームワーク。シンプルで柔軟な設計が特徴で、インタラクティブなウェブアプリケーションを作成するために開発者に人気がある。

Nuxt.jsは、Vue.jsの上に構築されたフレームワークで、サーバーサイドレンダリング、静的サイト生成、その他の高度な機能を提供する。

##### 主な違い

- **学習曲線:** Vueは初心者でもアクセスしやすい緩やかな学習曲線を持つ。Svelteも初心者に優しいが、コンパイル時の最適化という異なるアプローチを取っている。
- **パフォーマンス:** Svelteのコンパイル時の最適化は、Vueの仮想DOMと比較して、しばしば実行時のパフォーマンスを向上させる。
- **ツール:** Nuxt.jsは豊富なエコシステムと充実したドキュメントを提供している一方、SvelteKitは強力ではあるが、比較的新しく、コミュニティサポートもまだ成長段階にある。

#### ReactとNext.js

Reactは、コンポーネントベースのアーキテクチャと広範なエコシステムで知られる、広く使用されているJavaScriptライブラリ。

Next.jsは、React向けのフレームワークで、サーバーサイドレンダリング、静的サイト生成、その他多くの機能を提供する。

##### 主な違い

- **レンダリング:** SvelteKitとNext.jsはどちらもSSRとSSGを提供するが、Svelteのアプローチは仮想DOMを排除し、パフォーマンスが向上する可能性がある。
- **開発者体験:** Reactのエコシステムは成熟しており、広範である一方、Svelteのシンタックスとリアクティブモデルは新鮮でシンプルな代替手段を提供する。
- **コミュニティとエコシステム:** ReactとNext.jsは、比較的新しいSvelteKitよりも大きなコミュニティと、より多くのサードパーティー統合を持っている。

### 結論

Svelte（SvelteKit）は、ウェブ開発に新しい視点をもたらし、優れたパフォーマンスの向上と、モダンなウェブアプリケーション構築のためのアプローチを提供している。Vue（Nuxt.js）やReact（Next.js）は、豊富なエコシステムを持つ確立された堅牢なソリューションであるが、Svelteはコンパイル時の最適化とシンプルさで際立っている。

#### ユースケース: Svelte（SvelteKit）

- **シングルページアプリケーション（SPAs）:** SvelteKitのクライアントサイドルーティングのサポートや、最小限のバンドルサイズと高速なパフォーマンスにより、素早く読み込み、スムーズなユーザー体験を提供する必要があるSPAsに最適。
  
- **小規模から中規模のプロジェクト:** Svelteのシンプルさとボイラープレートコードの少なさは、開発スピードとメンテナンス性が重要な小規模チームやソロ開発者に理想的。

- **静的サイト生成（SSG）:** SvelteKitの静的サイト生成能力により、主に静的なコンテンツを持ち、時折動的な機能が必要なブログ、マーケティングサイト、ドキュメントプラットフォームに最適。

- **高度にインタラクティブなウェブアプリケーション:** Svelteのリアクティブモデルは、複雑なユーザーインタラクションを必要とし、低レイテンシが求められるダッシュボード、リアルタイムコラボツール、インタラクティブストーリーテリングプラットフォームに最適。

#### ユースケース: Vue（Nuxt.js）

- **プログレッシブウェブアプリケーション（PWAs）:** Vueの緩やかな学習曲線とNuxt.jsの強力な機能の組み合わせにより、ウェブ上でアプリのような体験を提供するPWAsの開発に最適。

- **大規模エンタープライズアプリケーション:** Vueの柔軟性とNuxt.jsのサーバーサイドレンダリングの取り扱い能力、さらに豊富なプラグインとツールのエコシステムにより、複雑なルーティングと状態管理を必要とする大規模アプリケーションに適している。

- **Eコマースプラットフォーム:** VueとNuxt.jsのモジュール構造、そしてVuexのような堅牢な状態管理ソリューションにより、SEO最適化と高速で信頼性の高いパフォーマンスを必要とする、機能豊富なEコマースプラットフォームの構築に理想的。

#### ユースケース: React（Next.js）

- **ユニバーサルアプリケーション:** Next.jsはサーバーとクライアントの両方でレンダリングされるユニバーサル（アイソモーフィック）アプリケーションの構築に優れており、コンテンツが多いウェブサイト、ニュースポータル、SEOが求められるアプリケーションに最適。

- **複雑なウェブアプリケーション:** Reactの広範なエコシステムと

### 最後に

適切なフレームワークを選ぶのは、プロジェクトの要件や個人的な好みによるところが大きい。SvelteとSvelteKitは、パフォーマンス、シンプルさ、モダンな開発手法を優先するプロジェクトに最適な選択肢だ。VueとNuxt.jsは、柔軟性と使いやすさのバランスを提供し、幅広い用途に適している。ReactとNext.jsは、強力なエコシステムと多様性を備え、複雑で大規模なプロジェクトに向いている。

これらのフレームワークの主な特徴と違いを理解することで、自分のウェブ開発プロジェクトに最適なツールを選び、効果的に活用することができる。

SvelteとSvelteKitの公式ドキュメントやコースを通じて、それらの特徴や利点、ユニークなポイントを探ってみた。この投稿では、Svelteについてのインサイトと、Vue（Nuxt.js）、React（Next.js）といった他の人気のあるフレームワークと比較した内容を共有する。

Svelteを探ってみた

Exploring Svelte

### Introduction

Working through the course [Haskell MOOC](https://haskell.mooc.fi) has been an educational experience, introducing me to the world of functional programming through the robust Haskell language. The course, designed for both beginners and even those familiar with functional programming, has provided a comprehensive foundation in Haskell, covering everything from basic syntax to advanced features like higher-order functions and algebraic data types.

### The course: Haskell MOOC

The course itself is divided into two individual large parts. It includes an excellent free online course material with examples and exercises. 

Working on the exercises involves knowing how to use the command line, and basic usage of the Git version control system.

There are two parts with a total of 16 lectures. Part 1 covers the basics of Haskell syntax and features sticking to pure functional programming, without side-effects. I/O (input-output) and Monads will be introduced in Part 2.

>**monad**: a design pattern used to handle computations in a sequence. It allows for chaining operations while managing side effects, encapsulating values, and providing a way to apply functions to these values.

All 16 lectures are roughly the same size, but some have more material than others. Each lecture set ends with 10-30 small programming exercises on the topics of the lecture. The course is completed by solving all the exercises.

#### Example of an exercise:
```haskell
------------------------------------------------------------------------------
-- Ex 3: implement the Euclidean Algorithm for finding the greatest
-- common divisor:
--
-- Given two numbers, a and b,
-- * if one is zero, return the other number
-- * if not, subtract the smaller number from the larger one
-- * replace the larger number with this new number
-- * repeat
--
-- For example,
--   myGcd 9 12 ==> 3
-- In this case, the algorithm proceeds like this
--
--   a      b
--
--   9      12
--   9      (12-9)
--   9      3
--   (9-3)  3
--   6      3
--   (6-3)  3
--   3      3
--   (3-3)  3
--   0      3
--
-- Background reading:
-- * https://en.wikipedia.org/wiki/Euclidean_algorithm
```

_※ My solution is at the end of the article._

### Haskell: A unique programming paradigm

#### Functional programming
Haskell is inherently functional. In Haskell, the primary building blocks are functions. Unlike imperative languages, where you write a series of instructions to change the state, Haskell focuses on the application of functions. This paradigm shift brings a unique set of advantages, especially in terms of code clarity and ease of reasoning.

#### Purity and side-effect free
One of the most compelling aspects of Haskell is its purity. Functions in Haskell do not have side effects, meaning they do not alter any state or interact with the outside world within their execution. This purity ensures that given the same inputs, a function will always return the same output, making Haskell code more predictable and easier to debug.

#### Laziness
Haskell employs lazy evaluation, meaning that expressions are only evaluated when needed. This allows for the creation of infinite data structures and can lead to performance optimizations by avoiding unnecessary calculations.

#### Strongly typed with type inference
Haskell’s type system is both strong and expressive. Every value and expression in Haskell has a type, which is checked at compile time, eliminating a whole class of runtime errors. Additionally, Haskell's compiler can infer types, reducing the need for explicit type annotations while maintaining type safety.

#### Use cases of Haskell
Haskell’s unique features make it suitable for a variety of applications:

- **Academic research and education**: Haskell's mathematical nature and purity make it an excellent tool for teaching and research in computer science and related fields.
- **Financial systems**: The predictability and reliability of Haskell’s pure functions make it ideal for financial modeling and quantitative analysis.
- **Compilers and interpreters**: Haskell’s strong type system and pattern matching capabilities are beneficial in writing compilers and interpreters.
- **Concurrent and parallel programming**: Haskell’s purity and immutability simplify reasoning about concurrent and parallel programs, reducing the complexity and potential for bugs.
- **Web development**: While not as mainstream as TypeScript, PHP, Go and such, Haskell has frameworks like Yesod that bring type safety and functional paradigms to web development.

### Comparing Haskell with TypeScript and Go
#### TypeScript
TypeScript, a superset of JavaScript, brings static typing to the dynamic world of JavaScript. While TypeScript improves the reliability and maintainability of JavaScript code, it remains fundamentally imperative and object-oriented, focusing on classes and mutable state.

- **Typing**: Both TypeScript and Haskell are statically typed, but Haskell’s type system is more expressive and enforced at compile time without the need for extensive annotations.
- **Paradigm**: TypeScript is multi-paradigm capable of being functional, but it does lean towards imperative and object-oriented programming, while on the other hand Haskell is purely functional.
- **Use cases**: TypeScript is primarily used for web development, enhancing JavaScript applications. Haskell, while also capable of web development, shines in areas requiring high reliability and mathematical applications.

#### Go
Go, developed by Google, is designed for simplicity and efficiency in systems programming. It is an imperative language with a focus on concurrency, making it popular for backend services and cloud applications.

- **Concurrency**: Go has built-in support for concurrent programming with goroutines, making it a strong candidate for networked services. Haskell also supports concurrency, but through a different paradigm using Software Transactional Memory (STM) and lightweight threads.
- **Simplicity vs. expressiveness**: Go emphasizes simplicity and ease of use, often at the cost of expressiveness. Haskell, on the other hand, provides a rich type system and advanced features, which can be more complex but offer greater power and safety.
- **Performance**: Go compiles to efficient machine code, similar to Haskell. However, Haskell’s lazy evaluation can sometimes introduce performance overhead, whereas Go’s performance is more predictable.

### Conclusion

The Haskell MOOC course has provided a deep understanding of Haskell’s functional programming paradigm, emphasizing its purity, laziness, and strong typing. While Haskell’s approach differs significantly from languages like TypeScript and Go, these differences also highlight its strengths, particularly in areas requiring mathematical precision and reliability. I think by continuing to learn and explore Haskell, it will strengthen my overall skills as a programmer by giving me opportunities to think a bit differently compared to the usual status quo of languages. Also I feel I can utilize the some of the code practices used in Haskell with other languages as well.

#### Solution
```haskell
euclideanAlg :: Integer -> Integer -> Integer
euclideanAlg a b
  | a == 0    = b
  | b == 0    = a
  | a > b     = euclideanAlg (a - b) b
  | otherwise = euclideanAlg a (b - a)
```

A quick dive into Haskell and its use cases with a short comparison between it, Typescript and Go. Also, I will describe the course I took for Haskell.

large_haskell_mooc.png

medium_haskell_mooc.png

small_haskell_mooc.png

thumbnail_haskell_mooc.png

haskell_mooc.png

### はじめに

[Haskell MOOC](https://haskell.mooc.fi)のコースを受講して、Haskell言語を使った関数型プログラミングの世界に足を踏み入れることができた。このコースは初心者だけでなく、関数型プログラミングに慣れた人にも設計されており、Haskellの基本的な構文から高階関数や代数的データ型などの高度な機能まで、包括的な基礎を提供してくれる。

### コース：Haskell MOOC

このコースは2つの大きな部分に分かれている。細かいながら分かり易い無料のオンラインコース教材が含まれており、例と演習が提供されている。

演習に取り組むには、コマンドラインの使用方法とGitバージョン管理システムの基本的な使い方を知っている必要がある。

全部で16回のチャプターがあり、2つのパートに分かれている。パート1では、Haskellの構文と機能の基本を扱い、副作用のない純粋関数型プログラミングに焦点を当てる。I/O（入出力）とモナドはパート2で紹介される。

> **モナド**（monad）：計算を順序だてて扱うためのデザインパターン。操作をチェーンし、副作用を管理しつつ、値をカプセル化し、これらの値に関数を適用する方法を提供する。

全16回のチャプターはおおむね同じボリュームだが、いくつかは他よりも多くの内容を含んでいる。各チャプターセットの最後には、そのチャプターのトピックに関する10～30のプログラミング演習があり、すべての演習を解くことでコースを完了させられる。

#### 演習の例:
```haskell
------------------------------------------------------------------------------
-- Ex 3: implement the Euclidean Algorithm for finding the greatest
-- common divisor:
--
-- Given two numbers, a and b,
-- * if one is zero, return the other number
-- * if not, subtract the smaller number from the larger one
-- * replace the larger number with this new number
-- * repeat
--
-- For example,
--   myGcd 9 12 ==> 3
-- In this case, the algorithm proceeds like this
--
--   a      b
--
--   9      12
--   9      (12-9)
--   9      3
--   (9-3)  3
--   6      3
--   (6-3)  3
--   3      3
--   (3-3)  3
--   0      3
--
-- Background reading:
-- * https://en.wikipedia.org/wiki/Euclidean_algorithm

```

_※自分で出した答えは記事の一番下にある。_

### Haskell：独自のプログラミングパラダイム

#### 関数型プログラミング
Haskellは本質的に関数型の言語であり、主要な構成要素は関数である。状態を変更する一連の命令を書く命令型言語とは異なり、Haskellは関数の適用に焦点を当てている。このパラダイムシフトは、コードの明快さと理論化の容易さの点で独自の利点をもたらす。

#### 純粋性と副作用のない関数（purity and no side effects）
Haskellの最も魅力的な側面の一つは、その純粋性である。Haskellの関数は副作用を持たない。つまり、実行中に状態を変更したり外部とやり取りしたりしない。この純粋性は、同じ入力が与えられた場合、関数が常に同じ出力を返すことを保証し、Haskellのコードを予測可能にし、デバッグを容易にする。

#### 遅延評価（lazy evaluation）
Haskellは遅延評価を採用しており、式は必要なときにのみ評価される。これにより、無限データ構造の作成が可能になり、不必要な計算を回避することでパフォーマンスの最適化が図れる。

#### 強い型と型推論（strong types with type-inference）
Haskellの型システムは強力かつ表現力豊かである。すべての値と式には型があり、コンパイル時にチェックされることで、ランタイムエラーのクラス全体を排除する。さらに、コンパイラは型を推論できるため、明示的な型注釈の必要性を減らしつつ、型安全性を維持する。

#### Haskellのユースケース
Haskellの独自の特徴は、多様なアプリケーションに適している:

- **学術研究と教育**: Haskellの数学的性質と純粋性は、コンピュータサイエンスおよび関連分野の教育と研究に最適である。
- **金融システム**: Haskellの純粋関数の予測可能性と信頼性は、金融モデリングおよび定量分析に理想的である。
- **コンパイラとインタプリタ**: Haskellの強力な型システムとパターンマッチング機能は、コンパイラやインタプリタの作成に有益である。
- **並行および並列プログラミング**: Haskellの純粋性と不変性は、並行および並列プログラムの理論化を簡素化し、バグの発生を減少させる。
- **Web開発**: TypeScript、PHP、Goなどほど主流ではないが、HaskellにはYesodのようなフレームワークがあり、型安全性と関数型パラダイムをWeb開発にもたらす。

### HaskellをTypeScriptおよびGoとの比較

#### TypeScript
TypeScriptはJavaScriptのスーパーセットで、動的なJavaScriptの世界に静的型付けをもたらす。TypeScriptはJavaScriptコードの信頼性と保守性を向上させるが、基本的には命令型およびオブジェクト指向であり、クラスや可変状態に焦点を当てている。

- **型付け**: TypeScriptとHaskellはどちらも静的に型付けされているが、Haskellの型システムはより表現力豊かで、広範な注釈なしにコンパイル時に強制される。
- **パラダイム**: TypeScriptは関数型も可能な多パラダイムだが、命令型およびオブジェクト指向プログラミングに傾いている。一方、Haskellは純粋に関数型である。
- **ユースケース**: TypeScriptは主にWeb開発に使用され、JavaScriptアプリケーションを強化する。HaskellはWeb開発も可能であるが、高い信頼性と数学的アプリケーションを必要とする分野で際立っている。

#### Go
GoはGoogleによって開発され、システムプログラミングの簡易性と効率性のために設計された。命令型言語であり、並行性に焦点を当てており、バックエンドサービスやクラウドアプリケーションで人気がある。

- **並行性**: Goはgoroutinesを使った並行プログラミングをサポートしており、ネットワークサービスの強力な候補となる。Haskellも並行性をサポートしているが、ソフトウェアトランザクショナルメモリ（STM）や軽量スレッドを使用する異なるパラダイムを通じてサポートしている。
- **簡易性 VS 表現力**: Goはシンプルさと使いやすさを強調しており、しばしば表現力を犠牲にする。Haskellは一方で、豊かな型システムと高度な機能を提供し、より複雑であるが、より強力で安全なプログラミングを可能にする。
- **パフォーマンス**: GoはHaskellと同様に効率的なマシンコードにコンパイルされる。ただし、Haskellの遅延評価は時折パフォーマンスオーバーヘッドを引き起こすことがあるのに対し、Goのパフォーマンスはより予測可能である。

### まとめ

Haskell MOOCコースは、Haskellの関数型プログラミングパラダイムについて深い理解を提供し、その純粋性、遅延評価、および強い型付けを強調している。HaskellのアプローチはTypeScriptやGoなどの言語とは大きく異なるが、これらの違いは特に数学的精度と信頼性を必要とする分野でのHaskellの強みを際立たせている。今後もHaskellを学び、探求し続けることで、一般的な言語の現状とは異なる視点を持つ機会が増え、プログラマーとしてのスキルを強化することができると感じている。また、Haskellで使われているベストプラクティスを他の言語にも活用できると感じている。

#### 答え
```haskell
euclideanAlg :: Integer -> Integer -> Integer
euclideanAlg a b
  | a == 0    = b
  | b == 0    = a
  | a > b     = euclideanAlg (a - b) b
  | otherwise = euclideanAlg a (b - a)
  ```

受講したHaskell MOOCコースを説明して、Haskell自体のユースケース等を紹介し、TypeScriptとGoとの簡単な比較を行う。

Haskellのコースを受講してみて学んだこと

Exploring Haskell: a dive into its use cases and comparison with other languages

Having to sync the filesystem state with a database, containing one-on-one relationships with the files, can be a tricky task. In this article, I will explain how I implemented my solution for this problem.

**All the code in the article is [GPL-3 licensed](https://github.com/Mangatsu/server/blob/main/COPYING).**

### Introduction

I have been developing a full-stack application called [Mangatsu](https://github.com/Mangatsu/server) for storing, managing, and reading various image collections, such as manga. It consists of a backend server application written in Go with secure API access and user control, and a client application written in TypeScript and Next.js. In this article, I will focus on the backend server application.

>The name "Mangatsu" is a play on the Japanese words "mangetsu" (満月, full moon) and "manga" (漫画, comic).

Mangatsu scans the directory paths provided by the user for manga, comics, doujinshi, and other collections (referred to as galleries from this point forward) and parses all the information it can from the filenames, included metadata files, and the pages themselves.

Mangatsu accepts two different directory structures:

```
📂 freeform
├── 📂 doujinshi
│       ├──── 📂 deeper-level
│       │     ├──── 📦 [Group (Artist)] 同人誌◯.cbz
│       │     └──── 📄 [Group (Artist)] 同人誌◯.json
│       ├──── 📦 (C99) [Group (Artist)] 漫画〇〇.zip
│       ├──── 📄 (C99) [Group (Artist)] 漫画〇〇.json
│       └──── 📦 (C88) [group (author, another author)] 単行本 [DL].zip # (JSON or TXT metafile inside)
├── 📂 art
│       ├──── 📂 [Artist] art collection
│       │     ├──── 🖼️ 0001.jpg
│       │     ├────...
│       │     └──── 🖼️ 0300.jpg
│       ├──── 📦 art collection XYZ.rar
│       └──── 📄 art collection XYZ.json
└── 📦 (C93) [group (artist)] 同人誌△ (Magical Girls).cbz
```

```
📂 structured
├── 📕 漫画１
│       ├── 📦 Volume 1.cbz
│       ├── 📦 Volume 2.cbz
│       ├── 📦 Volume 3.cbz
│       └── 📦 Volume 4.zip
├── 📘 漫画２
│       └── 📂 Vol. 1
│           ├── 🖼️ 0001.jpg
│           ├── ...
│           └── 🖼️ 0140.jpg
├── 📘 漫画３
│       └── 📂 Vol. 1
│           ├── 📦 Chapter 1.zip
│           ├── 📦 Chapter 2.zip
│           └── 📦 Chapter 3.rar
├── 📗 漫画４
│       ├── 📦 Chapter 1.zip
│       ├── ...
│       └── 📦 Chapter 30.rar
└── 📦 One Shot漫画.rar
```

As shown in the examples, numerous galleries are compressed in formats such as zip/cbz, rar/cbr, and 7zip. To avoid extracting the same file with each request, and to reduce server load and latency, it is not desirable to extract the file every time a user opens a gallery in the client. While caching the result on the client side is an option (and is used to some extent alongside server caching!), it can be unreliable, doesn't prevent abuse from bad actors, and, especially with applications like Mangatsu where the cached data can be huge, it is impractical for the client (browser, phone app, etc.).

### Implementing server-side file cache

... which is relatively simple.

First, this is how I initialize the cache directories.
```go
// InitPhysicalCache initializes the physical cache directories.
func InitPhysicalCache() {
	cachePath := config.BuildCachePath()
	if !utils.PathExists(cachePath) {
		err := os.Mkdir(cachePath, os.ModePerm)
		if err != nil {
		}
	}

	thumbnailsPath := config.BuildCachePath("thumbnails")
	if !utils.PathExists(thumbnailsPath) {
		err := os.Mkdir(thumbnailsPath, os.ModePerm)
		if err != nil {
		}
	}
}
```

Next, implementing functions to read from the cache and write to it. When writing to cache, there are two validations before extracting the gallery:

1. Does the cache directory already exist?
2. If it does, are there any files (i.e. pages) residing there?
3. If yes, then proceed to just return the residing files.
    - ※ If someone or something has corrupted the files in the cache, it would cause a problem here for the end user. I am considering writing additional validation here.

```go
// fetchFromDiskCache fetches the files from the disk cache and returns the list of files and the number of files.
func fetchFromDiskCache(dst string, uuid string) ([]string, int) {
	var files []string
	count := 0

	cacheWalk := func(s string, d fs.DirEntry, err error) error {
		if err != nil {
			log.Z.Error("failed to walk cache dir",
				zap.String("name", d.Name()),
				zap.String("err", err.Error()))
			return err
		}
		if d.IsDir() {
			return nil
		}

		// ReplaceAll ensures that the path is correct: cache/uuid/<arbitrary/path/image.png>
		files = append(files, strings.ReplaceAll(filepath.ToSlash(s), config.BuildCachePath(uuid)+"/", ""))
		count += 1
		return nil
	}

	err := filepath.WalkDir(dst, cacheWalk)
	if err != nil {
		log.Z.Error("failed to walk cache dir",
			zap.String("dst", dst),
			zap.String("err", err.Error()))
		return nil, 0
	}

	return files, count
}

// fetchOrExtractGallery extracts the gallery from the archive and returns the list of files and the number of files.
func fetchOrExtractGallery(archivePath string, uuid string) ([]string, int) {
	dst := config.BuildCachePath(uuid)
	if _, err := os.Stat(dst); errors.Is(err, fs.ErrNotExist) {
		return utils.UniversalExtract(dst, archivePath)
	}

	files, count := fetchFromDiskCache(dst, uuid)
	if count == 0 {
		err := os.Remove(dst)
		if err != nil {
			log.Z.Debug("removing empty cache dir failed",
				zap.String("dst", dst),
				zap.String("err", err.Error()))
			return nil, 0
		}

		return utils.UniversalExtract(dst, archivePath)
	}
	natsort.Sort(files)

	return files, count
}
```

The next section will detail how to sync this file cache with the server and the database.

### Implementing file locking

What happens if there are two or more requests trying to access a gallery at the same time? Especially in the case of a non-cached gallery, it would cause many unnecessary writes which in turn could cause corruption in the cached file themselves, and in the worst case, could get abused to crash the application or even the system.

To prevent this, I decided to use maps of mutexes. Essentially, I maintain a runtime map of all the cached galleries and their last access times, with mutexes to signal when a particular gallery cache is being written to.

```go
type cacheValue struct {
	Accessed time.Time   // Used to determine when the cache entry was last accessed for expiring and pruning purposes.
	Mu       *sync.Mutex // Mutex to ensure file-write-safety when accessing the cache.
}

type GalleryCache struct {
	Path  string                // Path to the cache directory.
	Store map[string]cacheValue // Map of Mutexes and access times for each cache entry.
}

var galleryCache *GalleryCache
```

Initializing the map and reading the existing cache into the map by iterating and verifying the cache directory:

```go
// InitGalleryCache initializes the abstraction layer for the gallery cache.
func InitGalleryCache() {
	galleryCache = &GalleryCache{
		Path:  config.BuildCachePath(),
		Store: make(map[string]cacheValue),
	}

	iterateCacheEntries(func(pathToEntry string, accessTime time.Time) {
		maybeUUID := path.Base(pathToEntry)
		if _, err := uuid.Parse(maybeUUID); err != nil {
			return
		}

		galleryCache.Store[path.Base(pathToEntry)] = cacheValue{
			Accessed: accessTime,
			Mu:       &sync.Mutex{},
		}
	})
}

// iterateCacheEntries iterates over all cache entries and calls the callback function for each entry.
func iterateCacheEntries(callback func(pathToEntry string, accessTime time.Time)) {
	cachePath := config.BuildCachePath()
	cacheEntries, err := os.ReadDir(cachePath)
	if err != nil {
		log.Z.Error("could not read cache dir",
			zap.String("path", cachePath),
			zap.String("err", err.Error()))
		return
	}

	for _, entry := range cacheEntries {
		info, err := entry.Info()
		if err != nil {
			log.Z.Error("could to read cache entry info",
				zap.String("path", cachePath),
				zap.String("err", err.Error()))
			return
		}

		pathToEntry := path.Join(cachePath, entry.Name())
		accessTime, err := atime.Stat(pathToEntry)
		if err != nil {
			log.Z.Debug("could to read the access time",
				zap.String("name", entry.Name()),
				zap.String("path", cachePath),
				zap.String("err", err.Error()))
			accessTime = info.ModTime()
		}

		callback(pathToEntry, accessTime)
	}
}
```

The galleries will be read with the following functions with the logic flowing as follows:

1. Check if the gallery exists in the runtime cache map
    1. If not, a new entry will be created.
    2. If it does, only the access time will be updated.
3. Lock the mutex to block any operations for the gallery.
4. If the gallery resides in the cache already, only the filepaths will be read and returned. If not, it will be extracted and copied.
5. Return filepaths and their count.
6. Release the mutex (notice the defer statement).

```go
// Read reads the gallery while updating the mutex and access time.
func Read(archivePath string, galleryUUID string) ([]string, int) {
	if _, ok := galleryCache.Store[galleryUUID]; !ok {
		galleryCache.Store[galleryUUID] = cacheValue{
			Accessed: time.Now(),
			Mu:       &sync.Mutex{},
		}
	} else {
		galleryCache.Store[galleryUUID] = cacheValue{
			Accessed: time.Now(),
			Mu:       galleryCache.Store[galleryUUID].Mu,
		}
	}

	galleryCache.Store[galleryUUID].Mu.Lock()
	defer galleryCache.Store[galleryUUID].Mu.Unlock()

	files, count := fetchOrExtractGallery(archivePath, galleryUUID)
	if count == 0 {
		return files, count
	}

	return files, count
}
```

Pruning expired cache entries according to their last access timestamps requires the use of mutexes as well. The PruneCache function runs every minute to clean up expired gallery caches.

```go
utils.PeriodicTask(time.Minute, cache.PruneCache)

// PeriodicTask loops the given function in separate thread between the given interval.
func PeriodicTask(d time.Duration, f func()) {
	go func() {
		for {
			f()
			time.Sleep(d)
		}
	}()
}
```

The PruneCache function iterates through the entire runtime cache map, locks the mutex while checking the access timestamp, and if expired, removes the cache entry from the map and deletes the files.

To ensure safe file removal, I am cautious not to remove anything other than the cache directory that starts with a UUID. This is verified by checking that the path begins with a valid UUID.

```go
// PruneCache removes entries not accessed (internal timestamp in mem) in the last x time in a thread-safe manner.
func PruneCache() {
	now := time.Now()
	for galleryUUID, value := range galleryCache.Store {
		value.Mu.Lock()
		if value.Accessed.Add(config.Options.Cache.TTL).Before(now) {
			if err := remove(galleryUUID); err != nil {
				log.Z.Error("failed to delete a cache entry",
					zap.Bool("thread-safe", true),
					zap.String("uuid", galleryUUID),
					zap.String("err", err.Error()))
			}
		}
		value.Mu.Unlock()
	}
}

// remove wipes the cached gallery from the disk.
func remove(galleryUUID string) error {
	// Paranoid check to make sure that the base is a real UUID, since we don't want to delete anything else.
	maybeUUID := path.Base(galleryUUID)
	if _, err := uuid.Parse(maybeUUID); err != nil {
		delete(galleryCache.Store, galleryUUID)
		return err
	}

	galleryPath := config.BuildCachePath(galleryUUID)
	if err := os.RemoveAll(galleryPath); err != nil {
		if errors.Is(err, fs.ErrNotExist) {
			delete(galleryCache.Store, galleryUUID)
		}
		return err
	}

	delete(galleryCache.Store, galleryUUID)

	return nil
}

```

### Closing

In this article, we've explored how to implement a simple file caching mechanism with mutexes in Go for a server. By using runtime maps and mutexes, safe concurrent access to cached galleries can be ensured while efficiently managing the cache. This approach not only reduces server load but also prevents potential issues from simultaneous access and cache corruption.

As the project evolves, I will continue to update this article with new insights and improvements. Thank you for reading, and I hope you found this guide helpful for your own projects!



Implementing server-side write-safe file caching with Go

large_banner.png

medium_banner.png

small_banner.png

thumbnail_banner.png

banner.png

ファイルシステムの状態を、ファイルと一対一の関係を持つデータベースと同期させることは、なかなか難しい作業である。この記事では、この問題に対する解決策をどのように実装したかを説明する。

**この記事に掲載されているすべてのコードは[GPL-3ライセンス](https://github.com/Mangatsu/server/blob/main/COPYING)となっている。**

### はじめに

漫画など様々な絵のコレクションも保存、管理、閲覧できるためのフルスタックアプリケーション[Mangatsu](https://github.com/Mangatsu/server)をオープンソースの形で開発している。構成としては、Goで書かれているサーバ側（APIアクセスとユーザー管理を提供等）と、TypeScriptとNext.jsで書かれているクライアントの形になっている。この記事では、主にサーバーアプリケーションに焦点を当てる。

>「Mangatsu」は「満月」と「漫画」の混ぜ言葉

Mangatsuは、ユーザーが指定したディレクトリパスをスキャンし、そこに置いている漫画、コミック、同人誌、およびその他のコレクション（以下はギャラリーと呼ぶ）のファイル名等を元にし、可能な限りの情報を解析してくれる。

ディレクトリ構造は2つの異なる型が可能となっている（freeform＝自由構造、structured＝体系立った構造）：

```
📂 freeform
├── 📂 doujinshi
│       ├──── 📂 deeper-level
│       │     ├──── 📦 [Group (Artist)] 同人誌◯.cbz
│       │     └──── 📄 [Group (Artist)] 同人誌◯.json
│       ├──── 📦 (C99) [Group (Artist)] 漫画〇〇.zip
│       ├──── 📄 (C99) [Group (Artist)] 漫画〇〇.json
│       └──── 📦 (C88) [group (author, another author)] 単行本 [DL].zip # (JSON or TXT metafile inside)
├── 📂 art
│       ├──── 📂 [Artist] art collection
│       │     ├──── 🖼️ 0001.jpg
│       │     ├────...
│       │     └──── 🖼️ 0300.jpg
│       ├──── 📦 art collection XYZ.rar
│       └──── 📄 art collection XYZ.json
└── 📦 (C93) [group (artist)] 同人誌△ (Magical Girls).cbz
```

```
📂 structured
├── 📕 漫画１
│       ├── 📦 Volume 1.cbz
│       ├── 📦 Volume 2.cbz
│       ├── 📦 Volume 3.cbz
│       └── 📦 Volume 4.zip
├── 📘 漫画２
│       └── 📂 Vol. 1
│           ├── 🖼️ 0001.jpg
│           ├── ...
│           └── 🖼️ 0140.jpg
├── 📘 漫画３
│       └── 📂 Vol. 1
│           ├── 📦 Chapter 1.zip
│           ├── 📦 Chapter 2.zip
│           └── 📦 Chapter 3.rar
├── 📗 漫画４
│       ├── 📦 Chapter 1.zip
│       ├── ...
│       └── 📦 Chapter 30.rar
└── 📦 One Shot漫画.rar
```

例に示されているように、多くのギャラリーはzip/cbz、rar/cbr、7zipなどの形式で圧縮されていることが多い。同じファイルをリクエストごとに解凍して、かえってサーバーの負荷と待ち時間の増加を防ぐため、ユーザーがクライアントでギャラリーを開くたびにファイルを解凍するのは望ましくでない。
クライアント側で結果をキャッシュ※することも一つの方法ではあるが、それは信頼性に欠け、悪意のあるユーザーによる乱用を防ぐことができず、特にMangatsuのようにキャッシュデータが非常に大きくなるアプリケーションでは、クライアント（ブラウザやスマートフォンアプリなど）にとって実用的ではないだと思う。

※実際にMangatsuでは両方、クライアントキャッシュとサーバキャッシュも併用している。クライアントの方は、ギャラリーごとにではなく、ページごとで管理されていて、ほぼ完全にブラウザに任せている形となっている。

### サーバー側ファイルキャッシュの実装

... こちらの方は割と簡単にできる。

まず、キャッシュディレクトリを初期化する方法：
```go
// InitPhysicalCache initializes the physical cache directories.
func InitPhysicalCache() {
	cachePath := config.BuildCachePath()
	if !utils.PathExists(cachePath) {
		err := os.Mkdir(cachePath, os.ModePerm)
		if err != nil {
		}
	}

	thumbnailsPath := config.BuildCachePath("thumbnails")
	if !utils.PathExists(thumbnailsPath) {
		err := os.Mkdir(thumbnailsPath, os.ModePerm)
		if err != nil {
		}
	}
}
```

次に、キャッシュから読み取るおよびキャッシュに書き込む関数の実装です。キャッシュに書き込む際には、ギャラリーを解凍する前に2つのチェックを行う：

1. キャッシュディレクトリはすでに存在しているのか？
2. もし存在するなら、そこにファイル（つまりページ）は置いているのか？
3. もし存在するなら、既存のファイルを返す。
    - ※  誰かまたは何かがキャッシュ内のファイルを破損させた場合、エンドユーザーに問題を引き起こす可能性がある。ここで追加のチェックを行うことを現在検討している。

```go
// fetchFromDiskCache fetches the files from the disk cache and returns the list of files and the number of files.
func fetchFromDiskCache(dst string, uuid string) ([]string, int) {
	var files []string
	count := 0

	cacheWalk := func(s string, d fs.DirEntry, err error) error {
		if err != nil {
			log.Z.Error("failed to walk cache dir",
				zap.String("name", d.Name()),
				zap.String("err", err.Error()))
			return err
		}
		if d.IsDir() {
			return nil
		}

		// ReplaceAll ensures that the path is correct: cache/uuid/<arbitrary/path/image.png>
		files = append(files, strings.ReplaceAll(filepath.ToSlash(s), config.BuildCachePath(uuid)+"/", ""))
		count += 1
		return nil
	}

	err := filepath.WalkDir(dst, cacheWalk)
	if err != nil {
		log.Z.Error("failed to walk cache dir",
			zap.String("dst", dst),
			zap.String("err", err.Error()))
		return nil, 0
	}

	return files, count
}

// fetchOrExtractGallery extracts the gallery from the archive and returns the list of files and the number of files.
func fetchOrExtractGallery(archivePath string, uuid string) ([]string, int) {
	dst := config.BuildCachePath(uuid)
	if _, err := os.Stat(dst); errors.Is(err, fs.ErrNotExist) {
		return utils.UniversalExtract(dst, archivePath)
	}

	files, count := fetchFromDiskCache(dst, uuid)
	if count == 0 {
		err := os.Remove(dst)
		if err != nil {
			log.Z.Debug("removing empty cache dir failed",
				zap.String("dst", dst),
				zap.String("err", err.Error()))
			return nil, 0
		}

		return utils.UniversalExtract(dst, archivePath)
	}
	natsort.Sort(files)

	return files, count
}
```

次のセクションでは、ファイルキャッシュをサーバーおよびデータベースと同期する方法について詳しく説明する。

### Mutexによるファイルロックの実装

大量のリクエストが同時にギャラリーにアクセスしようとした場合はどうなる、想像できる？特に、キャッシュされていないギャラリーだと、不要な書き込みが発生し、その結果、キャッシュされたファイル自体が破損されてしまう可能性が高くなる。最悪のケースでは、アプリケーションやシステムを落とせるように悪用されることもあり得る。

これを防ぐために、ミューテックス（mutex）のマップ（map）を使用することにした。基本的に、すべてのキャッシュされたギャラリーとその最終アクセス時間を記録するランタイムマップを維持し、特定のギャラリーキャッシュが書き込まれているときにシグナルを送るミューテックスを使用する。

```go
type cacheValue struct {
	Accessed time.Time   // Used to determine when the cache entry was last accessed for expiring and pruning purposes.
	Mu       *sync.Mutex // Mutex to ensure file-write-safety when accessing the cache.
}

type GalleryCache struct {
	Path  string                // Path to the cache directory.
	Store map[string]cacheValue // Map of Mutexes and access times for each cache entry.
}

var galleryCache *GalleryCache
```

Initializing the map and reading the existing cache into the map by iterating and verifying the cache directory:

マップを初期化し、キャッシュディレクトリを反復して検証することで、既存のキャッシュをマップに読み込む。

```go
// InitGalleryCache initializes the abstraction layer for the gallery cache.
func InitGalleryCache() {
	galleryCache = &GalleryCache{
		Path:  config.BuildCachePath(),
		Store: make(map[string]cacheValue),
	}

	iterateCacheEntries(func(pathToEntry string, accessTime time.Time) {
		maybeUUID := path.Base(pathToEntry)
		if _, err := uuid.Parse(maybeUUID); err != nil {
			return
		}

		galleryCache.Store[path.Base(pathToEntry)] = cacheValue{
			Accessed: accessTime,
			Mu:       &sync.Mutex{},
		}
	})
}

// iterateCacheEntries iterates over all cache entries and calls the callback function for each entry.
func iterateCacheEntries(callback func(pathToEntry string, accessTime time.Time)) {
	cachePath := config.BuildCachePath()
	cacheEntries, err := os.ReadDir(cachePath)
	if err != nil {
		log.Z.Error("could not read cache dir",
			zap.String("path", cachePath),
			zap.String("err", err.Error()))
		return
	}

	for _, entry := range cacheEntries {
		info, err := entry.Info()
		if err != nil {
			log.Z.Error("could to read cache entry info",
				zap.String("path", cachePath),
				zap.String("err", err.Error()))
			return
		}

		pathToEntry := path.Join(cachePath, entry.Name())
		accessTime, err := atime.Stat(pathToEntry)
		if err != nil {
			log.Z.Debug("could to read the access time",
				zap.String("name", entry.Name()),
				zap.String("path", cachePath),
				zap.String("err", err.Error()))
			accessTime = info.ModTime()
		}

		callback(pathToEntry, accessTime)
	}
}
```

ギャラリーは以下の関数で読み込まれ、ロジックは次のように進む：

1. ギャラリーがランタイムマップに存在するか確認する。
    1. ない場合は、新しいエントリを作成する。
    2. ある場合は、アクセス時間のみを更新する。
3. ミューテックスをロックして、ギャラリーの操作をブロックする。
4. ギャラリーファイルがすでにキャッシュにあった場合は、ファイルパスだけを読み取ってファイル名を返す。存在しない場合は、ギャラリーを解凍してコピーする。
5. ファイルパスとその数を返す。
6. ミューテックスを解除する（deferステートメントに注目）。

```go
// Read reads the gallery while updating the mutex and access time.
func Read(archivePath string, galleryUUID string) ([]string, int) {
	if _, ok := galleryCache.Store[galleryUUID]; !ok {
		galleryCache.Store[galleryUUID] = cacheValue{
			Accessed: time.Now(),
			Mu:       &sync.Mutex{},
		}
	} else {
		galleryCache.Store[galleryUUID] = cacheValue{
			Accessed: time.Now(),
			Mu:       galleryCache.Store[galleryUUID].Mu,
		}
	}

	galleryCache.Store[galleryUUID].Mu.Lock()
	defer galleryCache.Store[galleryUUID].Mu.Unlock()

	files, count := fetchOrExtractGallery(archivePath, galleryUUID)
	if count == 0 {
		return files, count
	}

	return files, count
}
```

最終アクセス時刻に基づいて期限切れのキャッシュエントリを削除するにも、ミューテックスの使用が必要。PruneCache関数は1分ごとに実行され、期限切れのギャラリーキャッシュをクリーンアップする。

```go
utils.PeriodicTask(time.Minute, cache.PruneCache)

// PeriodicTask loops the given function in separate thread between the given interval.
func PeriodicTask(d time.Duration, f func()) {
	go func() {
		for {
			f()
			time.Sleep(d)
		}
	}()
}
```

PruneCache関数はランタイムマップ全体を反復し、間ミューテックスをロックしてアクセス時刻をチェックする。そして、期限が切れている場合は、キャッシュエントリをマップから削除してファイルも削除する。

安全にファイルを削除するために、パスが有効なUUIDで始まっていることを確認ができたファイルしか削除しないように注意している。

```go
// PruneCache removes entries not accessed (internal timestamp in mem) in the last x time in a thread-safe manner.
func PruneCache() {
	now := time.Now()
	for galleryUUID, value := range galleryCache.Store {
		value.Mu.Lock()
		if value.Accessed.Add(config.Options.Cache.TTL).Before(now) {
			if err := remove(galleryUUID); err != nil {
				log.Z.Error("failed to delete a cache entry",
					zap.Bool("thread-safe", true),
					zap.String("uuid", galleryUUID),
					zap.String("err", err.Error()))
			}
		}
		value.Mu.Unlock()
	}
}

// remove wipes the cached gallery from the disk.
func remove(galleryUUID string) error {
	// Paranoid check to make sure that the base is a real UUID, since we don't want to delete anything else.
	maybeUUID := path.Base(galleryUUID)
	if _, err := uuid.Parse(maybeUUID); err != nil {
		delete(galleryCache.Store, galleryUUID)
		return err
	}

	galleryPath := config.BuildCachePath(galleryUUID)
	if err := os.RemoveAll(galleryPath); err != nil {
		if errors.Is(err, fs.ErrNotExist) {
			delete(galleryCache.Store, galleryUUID)
		}
		return err
	}

	delete(galleryCache.Store, galleryUUID)

	return nil
}

```

### まとめ

この記事では、Goを使ったサーバー側のファイルキャッシングをミューテックスで実装する方法を紹介した。
ランタイムマップとミューテックスを使うことで、キャッシュされたギャラリーへの安全な同期アクセスを確保しながら、効率的にキャッシュを管理することができる。このアプローチは、サーバーの負荷を減らすだけでなく、同期アクセスやキャッシュの破損による潜在的な問題を防ぐことができる。

プロジェクトが進化するにつれて、新しい知見や改善点をこの記事に更新していく予定。

読んでいただきありがとうございます。このガイドが皆さんのプロジェクトに約立てたら嬉しい。


サーバ側の書込み保護のファイルキャッシュをGoで実装

サーバ側の書込み保護のファイルキャッシュをGoで作ってみた

Server-side write-safe file caching with Go

The name Luukuton originates from a nickname I created for Minecraft around 10 years ago: _Luukku12_. It consists of the word "luukku", which is Finnish and means "hatch" or "trapdoor", and the number 12. There was no particular reason choosing this name back then. 

Going forward a year or two I wanted to get rid of the numbers in my name. That's when the name "Luukuton" was born. It basically means "without a hatch" or "hatchless" (a name I've actually used on some sites too!).  I was pretty happy with it at first.

But at some point I started to change my mind, probably a few years ago. I felt like the name was a bit too long and hard to pronounce in English. The meaning "without a hatch" wasn't really something I was fond of either. 

Now, thinking of a new name is hard. Especially because I wanted the next name to be **the one**. Something I wouldn't change ever again. So what I did? I didn't even think about it.

Fast-forwarding to this year, I started playing FFXIV (a great game by the way, go and play it). For some reason when I was creating my character, it just clicked. I found a name I really liked. Kohana Sengetsu, or 繊月小花 in kanji. Kohana being the first name and the one I would mostly be using in various places and Sengetsu last name. It's short and simple. It's also a Japanese one, which is a bonus as I've grown fond of the language on my journey of learning it for the past three and half years.

Kohana (小花) has the meaning of a small flower which is cute ❤️, and Sengetsu (繊月) in this case means crescent moon which you can think of as a small throwback to Tsukihime (100% cleared the remake before starting FFXIV, and I LOVED it). 

Signing off,

**Kohana, Kohana Sengetsu, CrescentKohana, 繊月小花, 🌙🌸**

A quick explanation why am I now called Kohana instead of Luukuton on the internet

Kohana Sengetsu, FFXIV player character, looking behind her shoulder in space while a star is shining

large_ffxiv_kohana_sengetsu.png

medium_ffxiv_kohana_sengetsu.png

small_ffxiv_kohana_sengetsu.png

thumbnail_ffxiv_kohana_sengetsu.png

ffxiv_kohana_sengetsu.png

Why I changed my internet nickname

Some great software I use daily.

### Cross-platform

- File archiver: [7-zip.org](https://www.7-zip.org)
- Great file indexing (search) tools: 
  - Windows: [voidtools.com](https://www.voidtools.com/)
  - Linux: [FSearch](http://cboxdoerfer.github.io/fsearch/)
- Password manager (everything below works together):
  - Windows:  [keepass.info](https://keepass.info/index.html)
  - Windows & Linux: [keepassxc.org](https://keepassxc.org)
  - Android: [KeePassDX](https://play.google.com/store/apps/details?id=com.kunzisoft.keepass.free)
- Torrenting: [qbittorrent.org](https://www.qbittorrent.org/)
- Scriptable PC remote control: [unifiedremote.com](https://www.unifiedremote.com/)

### Windows
- The best (in my opinion) music player on Windows: [AIMP](https://www.aimp.ru/)
- Image sharing, OCR and other tools: [ShareX](https://getsharex.com/)
- Better volume & media overlay: [Flyouts](https://github.com/ModernFlyouts-Community/ModernFlyouts)
- Better volume control: [EarTrumpet](https://github.com/File-New-Project/EarTrumpet)
- Emulating different locales: [Locale Emulator](https://xupefei.github.io/Locale-Emulator/)
- Useful tools by MS (e.g. batch rename and rebinding keys): [PowerToys](https://github.com/microsoft/PowerToys)

### Android
- 2FA: [Aegis](https://play.google.com/store/apps/details?id=com.beemdevelopment.aegis)
- Universal delivery tracking: [Deliveries](https://play.google.com/store/apps/details?id=de.orrs.deliveries)
- Reddit: [Sync for reddit](https://play.google.com/store/apps/details?id=com.laurencedawson.reddit_sync)


medium_WindowsTerminal.png

small_WindowsTerminal.png

thumbnail_WindowsTerminal.png

WindowsTerminal.png

幾つかお勧めの便利なアプリを紹介します。

### クロスプラットフォーム

-アーカイバ：[7-zip.org](https://www.7-zip.org)
- Great file indexing (search) tools: 
  - Windows：[voidtools.com](https://www.voidtools.com/)
  - Linux：[FSearch](http://cboxdoerfer.github.io/fsearch/)
- パスワードマネージャー（以下の全てが連動可能）
  - Windows：[keepass.info](https://keepass.info/index.html)
  - Windows & Linux：[keepassxc.org](https://keepassxc.org)
  - Android：[KeePassDX](https://play.google.com/store/apps/details?id=com.kunzisoft.keepass.free)
- ビットトレント：[qbittorrent.org](https://www.qbittorrent.org/)
- スクリプトも書けるPCリモート: [unifiedremote.com](https://www.unifiedremote.com/)

### Windows
- Windowsの場合、音楽プレイヤーと言えば：[AIMP](https://www.aimp.ru/)
- スクショ、OCR、色々便利なツール等：[ShareX](https://getsharex.com/)
- 音量とメディアオーバレイ：[Flyouts](https://github.com/ModernFlyouts-Community/ModernFlyouts)
- 音量調整：[EarTrumpet](https://github.com/File-New-Project/EarTrumpet)
- 幾つかのロケールをエムレート：[Locale Emulator](https://xupefei.github.io/Locale-Emulator/)
- 便利なツールのコレクション（例えば、ファイル名の一括変更、キーを再割り当て等）：[PowerToys](https://github.com/microsoft/PowerToys)

### Android
- 2FA（多要素認証）： [Aegis](https://play.google.com/store/apps/details?id=com.beemdevelopment.aegis)
- 宅配便、郵便トラッカー：[Deliveries](https://play.google.com/store/apps/details?id=de.orrs.deliveries)
- Reddit：[Sync for reddit](https://play.google.com/store/apps/details?id=com.laurencedawson.reddit_sync)


良く使っている色々なソフトウェアやアプリ。

お勧めのアプリ

Software I use

<div class="video-container">
<iframe width="840" height="473" src="https://www.youtube-nocookie.com/embed/esHOiWP2W98" title="Teaser Trailer" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen></iframe>
</div>

Over a hundred episodes worth of translated audio commentaries written by NISIOISIN himself.

- Masterpost and a guide to how to get them on [Reddit](https://www.reddit.com/r/araragi/comments/i2balw/monogatari_series_audio_commentaries_masterpost/)
- Detailed breakdown on [Sheets](https://docs.google.com/spreadsheets/d/1LCuqahTKzkdCFvRp6cL3hzUkMZFuYjgB53hrZgdZZHg/edit#gid=474706799)

Credits for all the translations goes to all the people listed on the Reddit post above. I've helped with proofreading (TLC) and fixing mistakes.

Over a hundred episodes worth of audio commentaries written by NISIOISIN himself. Translated.

large_bakemonogatari_commentary.jpg

medium_bakemonogatari_commentary.jpg

small_bakemonogatari_commentary.jpg

thumbnail_bakemonogatari_commentary.jpg

bakemonogatari_commentary.jpg

<div class="video-container">
<iframe width="840" height="473" src="https://www.youtube-nocookie.com/embed/esHOiWP2W98" title="Teaser Trailer" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen></iframe>
</div>

NISIOISIN本人に書いてある、物語シリーズの副音声全話（１００話以上）の英訳バージョン！

日本語が喋れる人にとって、そんなに意味がないかもしれないけれども、一応、英訳も存在しているよって日本人にも知らせたかったのです。

- マスターポストと入手方法はこちら、[Reddit](https://www.reddit.com/r/araragi/comments/i2balw/monogatari_series_audio_commentaries_masterpost/)にあります。
- 内容の解説：[Sheets](https://docs.google.com/spreadsheets/d/1LCuqahTKzkdCFvRp6cL3hzUkMZFuYjgB53hrZgdZZHg/edit#gid=474706799)

訳者や他プロジェクトに関わった人のクレジットは、上記のReddit投稿に記載されています。私は校正（TLC）と間違いの修正をやっていました。

１００話以上英訳されている物語シリーズの副音声エピソードが登場

物語シリーズ副音声

Monogatari Series Audio Commentaries

**tl;dr Colors might off when extracting frames etc. with ffmpeg if the file is not tagged correctly. Fix it by the command mentioned at the end. [A comparison](https://slow.pics/c/55al5mtZ) between everything.**

Something strange I noticed today (at the time of writing): a image I extracted with ffmpeg (command `ffmpeg -i episode.mkv q-%d.png`) from an episode of anime had different colors compared to when it was shown through mpv. I also tested MPC-HC, and mpv on Linux. Same results. I also tested the movie Kimetsu no Yaiba: Mugen Ressha-hen. Same thing happened.

I checked their meta data with ffprobe.

### Kobayashi-san Chi no Maid Dragon S2 - 01 (1080p [6B63C756])

- Command: `ffprobe -v error -show_streams .\file.mkv`
- Output:
  ```ini
  pix_fmt=yuv420p
  level=40
  color_range=unknown
  color_space=unknown
  color_transfer=unknown
  color_primaries=unknown
  ```

### Kimetsu no Yaiba: Mugen Ressha-hen (1080p.BD.Remux.DTS-HD.MA-TTGA)

- Command: `ffprobe -v error -show_streams .\file.mkv`
- Output:
  ```ini
  pix_fmt=yuvj420p
  level=-99
  color_range=pc
  color_space=bt470bg
  color_transfer=unknown
  color_primaries=unknown
  ```

It would seem that ffmpeg defaults to BT.601 even though the content nowadays is BT.709 (HDTV, BD) or BT.2020 (UHD) [1, 2] when color_space tag is set to **unknown**. This can be different for SD or otherwise old content though! The movie had color_space set to **bt470bg** (meaning PAL BT.601). That's most likely a mistake in the release itself (the BD or the BD ripper used). It should be BT.709 as it's a HD BluRay release. Japan uses NTCS so it's even more incorrect in that sense. smpte170m would be the NTSC equivalent for BT.601.

I feel that at least the unknown tag should be handled better in ffmpeg.

This can be fixed it by specifying the color_matrix in the command, like so: `ffmpeg -i INPUT.mkv -sws_flags +accurate_rnd+full_chroma_int -vf scale=in_color_matrix=bt709:out_color_matrix=bt709 q-%d.png`

The `-sws_flags +accurate_rnd+full_chroma_int` flag might not be as necessary, but it can help with accuracy. [A comparison](https://slow.pics/c/55al5mtZ) between everything.

Sources:
- [1] [Tweet](https://twitter.com/1977swthx/status/859048252716351489) (in Japanese)
- [2] [anime-tip.com](https://anime-tip.com/jamkun/vod/11118#toc19) (in Japanese)
- [blog.maxofs2d.net](https://blog.maxofs2d.net/post/148346073513/bt601-vs-bt709) (in English)


Screenshot from Kimetsu no Yaiba: Mugen Ressha-hen

large_kny.png

medium_kny.png

small_kny.png

thumbnail_kny.png

kny.png

Color conversion issues with ffmpeg

Opinionated settings (and some scripts) I've found to be great for anime with mpv. Surpassing the image quality of madvr (MPC-HC/NGU algorithm).

<h3 id="tldr"><a href="/article/mpv-for-anime#tldr"># TL;DR / Quick Guide</a></h3>

1. Install [mpv](https://mpv.io/installation)
   - This guide is based on [the stable release v0.38.0](https://github.com/mpv-player/mpv/releases/tag/v0.38.0) and also should work with the latest git version (tested on 2024-07-08)
   - [mpv manual](https://mpv.io/manual)
3. Download shaders and place them to `mpv/shaders/`: 
	1. Luma Upscaler:
	   - For most modern GPUs [ArtCNN_C4F32](https://raw.githubusercontent.com/Artoriuz/ArtCNN/main/GLSL/ArtCNN_C4F32.glsl)
	   - **or**
	   - For very high-end GPUs [ArtCNN_C4F16](https://raw.githubusercontent.com/Artoriuz/ArtCNN/main/GLSL/ArtCNN_C4F16.glsl)
	2. Chroma Up/Downscaler: [ArtCNN_C4F32_Chroma](https://github.com/Artoriuz/ArtCNN/blob/main/GLSL/ArtCNN_C4F32_Chroma.glsl)
4. Copy & paste the [image quality config below](/article/mpv-for-anime#conf_image_quality) to `mpv/mpv.conf`
5. Uncomment either ArtCNN_C4F32_Chroma at the Chroma section in the config if desired. Won't be too much of a difference as changes in Chroma are harder to notice.
6. (Optional, Windows) Comment the two Vulkan lines and uncomment DirectX lines at the start of the config for better performance in some cases
7. (Optional) Download and place scripts to `mpv/scripts/`


### Links
- **[mpv](https://mpv.io)**
- SOURCES & REFERENCES
  - [artoriuz.github.io](https://artoriuz.github.io/blog/mpv_upscaling.html) (mathematic and most up to date)
  - [iamscum.wordpress.com](https://iamscum.wordpress.com/guides/videoplayback-guide/mpv-conf/)
  - A comparison between FSRCNNX and SSSR and madVR by me: [slow.pics/c/NTryj7wb](https://slow.pics/c/NTryj7wb) (not up to date!)
- SHADERS
  - Shaders: [ArtCNN](https://github.com/Artoriuz/ArtCNN)
 - SCRIPTS
   - [mpvacious](https://github.com/Ajatt-Tools/mpvacious) (real-time Anki cards with a press of a button)
   - [autoload](https://github.com/mpv-player/mpv/blob/master/TOOLS/lua/autoload.lua) (autoplay next episode)
   - [betterchapters](https://github.com/mpv-player/mpv/issues/4738#issuecomment-321298846)
   - [bookmarker](https://github.com/NurioHin/mpv-bookmarker)
   - [webm](https://github.com/ekisu/mpv-webm) (quickly create video clips while watching)
   - [autosubsync](https://github.com/joaquintorres/autosubsync-mpv) (**automatically sync subtitles** to another subtitle or even **just to the audio track**)

### Index
- [tldr](/article/mpv-for-anime#tldr)
- [mpv.conf for image quality](/article/mpv-for-anime#conf_image_quality)
- [other settings in my mpv.conf](/article/mpv-for-anime#conf_other)
- [input.conf](/article/mpv-for-anime#conf_input)
- [refresh rate in mpv.conf](/article/mpv-for-anime#conf_hz)
- [changelog](/article/mpv-for-anime#changelog)

<h3 id="conf_image_quality"><a href="/article/mpv-for-anime#conf_image_quality"># mpv.conf for image quality</a></h3>

```ini
# Load mpv's default quality settings
profile=high-quality

# Not too useful on modern hardware. 'auto-copy-safe' is a safe option to use if one wants to enable it. Defaults to 'no'.
#hwdec=no

# Video driver to use. The latest gpu-next is recommended.
vo=gpu-next

###### Vulkan on Linux, Windows or macOS (recommended)
gpu-api=vulkan

###### DirectX on Windows (recommended if issues on Vulkan on Windows)
#gpu-api=d3d11

###### Shaders ######

###### Luma up (use ArtCNN_C4F32 if the GPU can handle it)
glsl-shader="~~/shaders/ArtCNN_C4F16.glsl"
#glsl-shader="~~/shaders/ArtCNN_C4F32.glsl"
scale=ewa_lanczos
scale-blur=0.981251

###### Luma down
dscale=catmull_rom

###### Chroma up + down (not important but if the GPU is not being used much anyway, might as well)
#glsl-shader="~~/shaders/ArtCNN_C4F32_Chroma.glsl"

# fruit: 8-Bit/8-Bit+FRC display
# ordered: true 10-Bit/12-Bit display
# error-diffusion: high-end GPUs
dither=error-diffusion
dither-depth=auto
error-diffusion=sierra-lite # uncomment if not 'error-diffusion'

###### Antiring
scale-antiring=0.5
dscale-antiring=0.5
cscale-antiring=0.5

###### Debanding
deband=yes
deband-iterations=4
deband-threshold=35
deband-range=16
deband-grain=4
```

<h3 id="conf_other"><a href="/article/mpv-for-anime#conf_other"># Other settings in my mpv.conf</a></h3>

```ini
###### General
autofit=50%       # Open mpv as half the monitor resolution
keep-open=yes
snap-window=yes       # Snap to corners on Windows
cursor-autohide=1000
save-position-on-quit # Remember position when closing the player
osd-bar=no            # No huge box on screen when turning the volume
osd-font-size=32
volume=100
volume-max=100
audio-exclusive=no    # A hotkey for this inside input.conf (k cycle audio-exclusive)

###### Language & subtitles
sub-visibility=no      # Hide subtitles by default
alang=jp,jpn,ja,en,eng # Language priority for audio
slang=jp,jpn,ja,en,eng # Language priority for subtitles
sub-auto=fuzzy
sub-font='Arial'
sub-font-size=40
sub-border-size=1
sub-shadow-color=0.0/0.0/0.0/0.50
sub-shadow-offset=2

###### High-quality screenshots
screenshot-format=webp
screenshot-webp-lossless=yes
screenshot-high-bit-depth=yes
screenshot-sw=no
screenshot-directory="~~/screenshots"
screenshot-template="%f-%wH.%wM.%wS.%wT-#%#00n"
```

<h3 id="conf_input"><a href="/article/mpv-for-anime#conf_input"># input.conf</a></h3>

```ini
##### General
z          ignore
w          no-osd cycle sub-visibility
s          cycle sub
S          cycle sub down
F1         add sub-delay -0.1   
F2         add sub-delay +0.1
F5         no-osd screenshot
k          cycle audio-exclusive
p          add panscan -0.1
P          add panscan +0.1

WHEEL_UP   add volume   2
WHEEL_DOWN add volume  -2
RIGHT      seek   2 exact
LEFT       seek  -2 exact
UP         seek   5 exact
DOWN       seek  -5 exact
Ctrl+RIGHT seek  20 exact
Ctrl+LEFT  seek -20 exact

##### mpvacious
q          script-binding mpvacious-sub-seek-back
e          script-binding mpvacious-sub-seek-forward
x          script-binding mpvacious-sub-rewind

##### Better Chapters
MOUSE_BTN7 script_binding chapter_prev
MOUSE_BTN8 script_binding chapter_next

##### Bookmarker Menu
B          script_message bookmarker-menu
b          script_message bookmarker-quick-save
ctrl+b     script_message bookmarker-quick-load
```

<h3 id="conf_hz"><a href="/article/mpv-for-anime#conf_hz"># Refresh rate in mpv.conf</a></h3>
If for some reason (e.g. to have an exact match) you want to have the refresh rate to be specified, comment out these two lines. Can cause problems especially if the fps doesn't match with the display. mpv is usually pretty good at estimating the fps anyway so no real need to use these.

Refresh rate reported by the OS can be verified with [testufo](https://www.testufo.com/refreshrate).

```ini
# Refresh rate of the monitor (143.856 = 6* 23.976, which is the standard video framerate)
override-display-fps=143.856

# 'display-vdrop' is basically the same as 'audio', but with better debugging in Shift+i menu
# Read more about this here: https://mpv.io/manual/master/#options-video-sync
video-sync=display-vdrop
```

<h3 name="changelog" id="changelog"><a href="/article/mpv-for-anime#changelog"># CHANGELOG</a></h3>

```md
=================================
+ Added
- Removed or disabled
* Change/information
=================================
=== 2024-12-14
* Updated deprecated 'profile=gpu-hq' to 'profile=high-quality'
=== 2024-07-08
+ Added ArtCNN
+ Added a strong recommendation for 'gpu-next'
+ Added dither options
- Removed Anime4K section
- Removed FSRCNN, KrigBilateral and SSim references in favour of ArtCNN and built-in shaders
* Updated to mpv 38.0
* Changed the structure of the config
* Adjusted (lowered) antiring and deband values\
* Simplified the guide a bit
=== 2022-07-11
+ Added a bit about hwdec and vo to the config
+ Added a step to the tl;dr guide to uncomment the Luma up shader in the config
=== 2022-04-03
+ Added more comments to explain some of the config options
* Make Vulkan default option with an optional step for Windows to switch to DirectX
* Changed how paths are defined to make them work out of the box
=== 2022-03-14
+ Added a bit about the mpv version this guide is based on
+ Added gamut-mapping-mode in mpv git to the config
* Commented out gamut clipping settings by default
=== 2022-02-22
* Fixed section title links
* Modified some phrasings
- Removed API (DirectX, OpenGL, Vulkan) partiality
=== 2021-12-18
+ Added a quick guide
* Modified comments and structure of the config
=== 2021-10-24
+ Added gamut-clipping and hdr-compute-peak to the config
=== 2021-09-26
* Fixed a typo
=== 2021-08-31
* More about anime4K
* Fixed anchor links
=== 2021-08-01 ===
+ Added a bit about Adaptive Sharpening
=== 2021-07-10 ===
+ Added autosubsync script
+ Added a new source: artoriuz.github.io
+ Added a comparison: slow.pics/c/NTryj7wb
+ Added index
+ Added changelog
+ Added FSRCNNX
+ Added correct-downscaling=yes
- Disabled ThinLines
* Made the structure a bit clearer
* Moved the bit about refresh rates to its own section

=== Initial version ===
```


High-quality configuration for watching anime with mpv.

Ononoki Yotsugi sitting inside a crane game

large_Tsukimonogatari_02_09_59_394_c039deef29.png

medium_Tsukimonogatari_02_09_59_394_c039deef29.png

small_Tsukimonogatari_02_09_59_394_c039deef29.png

thumbnail_Tsukimonogatari_02_09_59_394_c039deef29.png

Tsukimonogatari_02_09_59_394_c039deef29.png

mpv for anime

### Tweaks with Group Policy Manager 

**Windows 10 might force old and possibly unstable graphics, chipset and other drivers to your system. To properly disable automatic driver updates on W10:**

1. Search for Group Policy from Start Menu
2. Computer Configuration > Administrative Templates > Windows Components > Windows Update > double click *Do not include drivers with Windows Update* > Enabled
3. Computer Configuration > Administrative Templates > System > Device Installation > double click *Prevent device metadata retrieval from the Internet* > Enabled
4. Computer Configuration > Administrative Templates > System > Device Installation > double click *Specify search order for device driver source locations* > Disabled

It might also be a good idea to disable this:

<img src="https://strapi.kohana.fi/uploads/w10_automatic_drivers_84b603a774.png" width="900"/>

**Detailed status while startup, shutdown and updates:**
1. Search for Group Policy from Start Menu
2. Computer Configuration > Administrative Templates > System > double click *Display highly detailed status messages* > Enabled

**Disable automatic restarts for updates:**
1. Search for Group Policy from Start Menu
2. Computer Configuration > Administrative Templates > Windows Components > Windows Update > double click *No auto-restart with logged on users for scheduled automatic updates installations* > Enabled

**Stop Windows waking up from sleep**
1. Search for Group Policy from Start Menu
2. Computer Configuration > Administrative Templates > Windows Components > Windows Update > double click *Enabling Windows Update Power Management* > Disabled

Group Policy Editor is only available on Windows 10 Pro! On Home-version you need to manually install Group Policy Editor first (or this might also be achievable through registry editor.)

Group Policy Editor for W10 Home users [here](https://www.itechtics.com/easily-enable-group-policy-editor-gpedit-msc-in-windows-10-home-edition/).

### Refresh rate
<img src="https://strapi.kohana.fi/uploads/win10_hz_e54365d0b5.gif" width="600"/>

### Startup Programs
1. CTRL + Shift + ESC ->  Startup -> Disable everything useless
2. Win + R -> msconfig -> Services -> Hide all Microsoft services -> Disable everything useless

### Power Plans
I prefer this being set to the High Performance plan but nowadays any Ryzen plan (if on Ryzen) or Balanced should be fine as well.
<br/><br/>
<img src="https://strapi.kohana.fi/uploads/win10_powerplans_ca9d9727da.png" width="600"/>

### Disable Fast Start-up
It's debatable if one would want to disable this. I prefer it being disabled as with an NVMe SSD my boot times are already fast, and fast start-up can cause weird bugs with Windows.
<br/><br/>
<img src="https://strapi.kohana.fi/uploads/w10_fast_startup1_caac8ac820.png" width="600"/>
<br/><br/>
<img src="https://strapi.kohana.fi/uploads/w10_fast_startup2_fd124b115c.png" width="600"/>

### Debloater

Some scripts to debloat Windows: [github.com/Sycnex/Windows10Debloater](https://github.com/Sycnex/Windows10Debloater)

large_windows-10-logo.png

medium_windows-10-logo.png

small_windows-10-logo.png

thumbnail_windows-10-logo.png

windows-10-logo.png

Tweaks for Windows 10

**Prerequisites**
- [UNi drivers](http://maxedtech.com/asus-xonar-unified-drivers) (UNi Xonar W10 1825 v1.81a r2 for W10 or UNi Xonar 1816/1823 v1.80a r3 for W7, W8 & W10)
- [XonarSwitch](http://maxedtech.com/xonarswitch-beta-testing) (latest)



**Step-by-step installation and configuration instructions**
1. Select "Low DPC Latency", "Run driver cleaning", "Re-enable stereo upmix" and choose your sound card from the "Default card profile" list: <br/><br/><img src="https://strapi.kohana.fi/uploads/uni_installation_b8f8449fb1.png" alt="driver installation prompt" width="400"/>

2. *[Optional, this may lower DPC latency]* After you've installed the drivers, restart your computer and after that press Win+R key combination; type "msconfig" there and continue. In the programs tab disable "Windows host process (Rundll32)": <br/><br/><img src="https://strapi.kohana.fi/uploads/cmedia_7cd08ddc96.png" alt="process name" width="400"/>

3. Place the XonarSwitch.exe in desired location and launch it.
4. **Output tab:** Select "2 Channels" from the Source channels list, and set the Bit Depth to 24bit (or 16bit, there's not that much of a difference) and Sample Rate to 44.1Khz.
5. **Output tab:** Click the Amp button and select an appropriate impedance level from the list depending on your headphones (VOIP is for 0 - 32 ohm headphones, Pro-gaming for 32 - 64 ohm and Exciter for 64 - 150 ohm). I recommend using the rear 3.5mm connection because it has less interference (Rear Headphones): <br/><br/><img src="https://strapi.kohana.fi/uploads/output_894280e7f8.png" alt="output impedance" width="400"/>

6. **Mixer tab:** Set L and R playback volume to 45% or less (this is because over 45% might cause clipping in your audio).
7. **Mixer tab:** Set the microphone (record) volume to whatever value you like and click the settings button (* icon). Disable the front mic if you're using the rear port (which is recommended) and decide do you want to use mic boost: <br/><br/><img src="https://strapi.kohana.fi/uploads/mixer_be94371bcf.png" alt="volume mixer" width="400"/>

8. **Equalizer / FlexBass:** Adjust the equalizer if you need to and disable FlexBass: <br/><br/><img src="https://strapi.kohana.fi/uploads/eq_153bd5182e.png" alt="equalizer" width="400"/>


9. **AEC:** Disable AEC.
10. You can find additional options by right clicking the XonarSwitch icon which you can find in the taskbar: <br/><br/><img src="https://strapi.kohana.fi/uploads/taskbar_rightclick_bdc62cc904.png" alt="taskbar" width="200"/>


12. **Options:** You can backup and restore the settings of the UNi drivers and completely uninstall the drivers. Set the XonarSwitch launch automatically on startup: <br/><br/><img src="https://strapi.kohana.fi/uploads/options_startup_6787a1236c.png" alt="startup options" width="400"/> 
 
12. **Profiles:** You can create multiple profiles. For example if you want to use surround while watching movies you can create a specific profile for that which you can activate by pressing a custom key combination (eg. CTRL+ALT+1): <br/><br/><img src="https://strapi.kohana.fi/uploads/profiles_07e47c187b.png" alt="profiles" width="400"/>



Step-by-step installation and configuration instructions for UNi Xonar drivers

Blog Filter posts by clicking tags below