Sync Gateway利用方法：チャネル

## はじめに

Sync Gatewayを利用するために必要となる、チャネルについての理解を助ける情報を整理します。


## コンセプト
Sync Gatewayはチャネルを使用して、効果的なアクセス制御を維持しながら、大規模なユーザーの間でデータベースのドキュメントを簡単に共有できるようにします。チャネルを介して、ドキュメントとユーザーの間のセキュリティコントロールを行うことができます。

## 概要
データベース内のすべてのドキュメントには、配布先のチャネルのリストが割り当てられています。ユーザー（またはロール）に対して、チャネルのリストへのアクセスが許可されます。これらの目的は、チャネルの使用方法に反映されています。

- ユーザーにチャネルへのアクセスを許可することによる、アクセス制御
- ドキュメントをチャネルに割り当てることによる、ドキュメントルーティング

通常、チャネルを使用して次のことを行います。

- 誰が何にアクセスできるかを制御する
- データセットを分割する
- ユーザーが必要なドキュメントだけにアクセスできるようにする
- モバイルデバイスに同期されるデータの量を最小限に抑える

チャネルには、あらかじめ存在するシステムチャネルと、ユーザーが作成するプライベートチャネルがあります。

## チャネル割り当て

以下の図に示すように、チャネルは、以下のふたつの方法で構成します。

- Sync関数
- REST API

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/176567/40d28f10-f603-8073-319c-863f344c70b4.png)

### Admin REST API
Admin REST APIエンドポイント（`/{tkn-db}/_user/{name}`）に対して、`admin_channels`プロパティを用いて構成できます。

### Sync関数
Sync関数は、ドキュメントへのアクセスを制御し、ルーティングするための柔軟かつ安全な方法を提供します。Sync関数内で、レプリケーション対象のドキュメントのプロパティから適切なアクセスおよびチャネルルーティングのための情報を取得するようにプログラミングすることができます。また、ドキュメントの拡張属性（XATTR）を利用することも考えられます。

## ユースケース
2人のユーザーがドキュメントのプライベートセットと1人の共有ドキュメント共有へのアクセスを必要とし、許可されている場合を考えてみます。次の図を参照してください。


![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/176567/0f754ef3-1c5d-385b-4c1a-62e0df7f7117.png)


この場合、各ユーザーは、ユーザーのみがアクセスできるドキュメントのサブセットと、共通のドキュメントを含む共有チャネルを持つプライベートチャネルに割り当てられます。この例のユーザーは、ロールに置き換えることができます。

このモデルの例として、すべての店舗がSync　Gatewayユーザーに対応する小売チェーンが考えられます。各ストアには、価格設定、プロモーション、在庫などの店舗固有のドキュメントを含む店舗固有のチャネルがあります。さらに、すべての店舗は、小売店の場所、製品カタログなどの共通のドキュメントセットにアクセスします。

## チャネルの種類

### システムチャネル

#### パブリックチャンネル
パブリックチャンネル（記号「！」で表されます）は、誰でも利用可能なドキュメントのためのチャンネルです。これは、ユーザー全体で情報を利用できるようにするために使用されます。

`channel()`関数を使用して、パブリックチャネルにドキュメントを割り当てます。

このチャネルに割り当てられたドキュメントには、すべてのユーザーがアクセスできます。パブリックチャンネルにアクセスするために、ユーザーに特明示的にチャネルアクセスを割り当てる必要はありません。ユーザーには、パブリックチャネルへのアクセスが自動的に許可されます。

#### オールドキュメントチャネル
オールドキュメントチャネル（記号「*」で表現されます）は、すべてのドキュメントを表す内部チャネルです。

このチャネルへの割り当ては自動的かつ暗黙的です。チャネルにドキュメントを明示的に割り当てたり、チャネルからドキュメントを削除したりすることはできません。

このチャネルを、アクセス許可でのすべてのチャネルのワイルドカードの使用と混同しないでください。

#### オールチャネルワイルドカード
オールチャネルワイルドカード（「*」） は、ユーザーのアクセスを許可するときに使用されますが、これにより、任意のチャンネル（内の任意のドキュメント）へのアクセスを許可することになります。

`access()`メソッドを使用して、Sync関数で動的にユーザーアクセス許可を行うことができます。

オールチャネルワイルドカードを使用してユーザーにアクセスを許可すると、ユーザーは、プライベートチャネルからのものを含め、任意のチャネル（のすべてのドキュメント）にアクセスできます。

オールチャネルワイルドカードを利用する場合、以下について気を付ける必要があります。

- オールチャネルワイルドカードアクセスを持つユーザーによるレプリケーションは、すべてのドキュメントをプルします。大量のデータを同期する可能性があるため（syncはバケット内のすべてのドキュメントをプルします）、オールチャネルワイルドカードを持つユーザーは、チャネルフィルターを使用して、同期するチャネルに明示的に名前を付ける必要があります。

- オールチャネルワイルドカードを使用してアクセスを許可されたユーザーは、特定のチャネルに対する`requireAccess()`権限を継承しません。

- 同期によって大量のドキュメントがモバイルデバイスに不必要にプルされるのを防ぐために 、オールチャネルワイルドカードとフィルターを組み合わせて使用します。

### プライベートチャネル

Sync関数内でチャネルにドキュメントを割り当てます。プライベートチャネルは、ドキュメントが割り当てられるときに作成されます。

## チャネル名仕様
有効なチャネル名は、テキスト文字[ A–Z、a–z]、数字[ 0–9]、およびいくつかの特殊文字[ = + / . , _ @]で構成されます。チャネル名では大文字と小文字が区別されます。

## チャネル制限

|エレメント|制限要因|チャネル数最大数目安|
|---|---|---|
|ドキュメントごとのチャネル|チャネルとアクセス許可の合計数によって消費されるメモリの量は、xattrサイズ制限最大1Mb内に収まる必要があります。|50|
|ユーザーあたりのチャネル|チャネルによって消費されるメモリの量は、メタデータを格納するためにCouchbase　Serverのドキュメントで利用可能な20MB以内に収まる必要があります。|1,000|


#### 同期メタデータの制限
ドキュメントが新しいチャネルに割り当てられるたびに、チャネル名がそのドキュメントの同期メタデータに追加されます。

したがって、ドキュメントのチャネルセットは、許可された同期メタデータサイズによって制限されます。
Sync Gatewayは、同期メタデータが許可された制限を下回っている限り、ドキュメントを新しいチャネルに割り当てます。


|`enable_shared_bucket_access`の値| サイズ（ドキュメントあたりのMb）|
|---|---|
|false|20|
|true|1|



チャネル数が同期メタデータの使用可能スペースを超えた場合には、ドキュメントごとの同期メタデータのサイズを小さくするには、次のいずれかを実行します。

- ドキュメントあたりのチャネル数を減らします。
- チャネル名を短くします。チャネル名が短いほど、占有するスペースが少なくなります。
- `revs_limit`の値を下げます。実際、チャネルメタデータのコピーは、ドキュメントのリビジョンごとに保持されます。


## チャネル管理


管理REST APIの`_role`エンドポイント（`/{tkn-db}/_user/{name}`）にPUTリクエストを送信して、ユーザーにチャネルを追加します。`{name}`は、更新するユーザー名です。

管理REST APIの`_role`エンドポイント（`/{tkn-db}/_role/{name}`）にPUTリクエストを送信して、ユーザーにチャネルを追加します。`{name}`は、更新するロール名です。

`admin_channels`プロパティで割り当てるチャンネルを指定します。

```BASH
$ curl -vX PUT "http://localhost:4985/mydatabase/_user/{user}" -H 
"accept: application/json" -H "Content-Type: application/json" -d
'{ "admin_channels": ["Channel1","Channel3]}' 
```



# 関連情報
https://docs.couchbase.com/sync-gateway/3.0/access-control-concepts.html