# crawler-service

このリポジトリは、ドローン航路のあり方に係る調査・研究として、ドローン航路システムに係る分散カタログシステムのサンプルを公開しています。

## 目次

- [システム概要](#システム概要)
- [設定](#設定)
- [起動方法](#起動方法)
- [使用方法](#使用方法)
- [ライセンス](#ライセンス)
- [免責事項](#免責事項)

## システム概要

分散カタログは、複数のドメインアプリケーションが公開するSPARQLエンドポイントからRDFデータを収集・格納し、データを構造的に把握・解釈することを可能にするサービスです。

| 機能 | 概要 |
|------|------|
| 外部へのクエリ発行 | ドメインアプリケーションに対してSPARQLクエリ（基本的にはSELECTのみ）を直接発行 |
| クローリング | RDFサーバーから全トリプルデータを取得してキャッシュに格納 |
| キャッシュへのクエリ発行 | キャッシュ（GraphDB）に対してSPARQLクエリを発行 |
| 差分更新 | RDFデータの差分更新（RDFPatch）を受信し、キャッシュに反映 |
| 更新通知 | キャッシュ更新時にMQTTで外部システムへ通知 |

### クローリング方式

**全トリプル取得方式**を採用しています：

- RDFサーバーのSPARQLエンドポイントに対して `CONSTRUCT { ?s ?p ?o } WHERE { ?s ?p ?o }` クエリを実行
- default graphの全トリプルを取得（Named Graphは順序制御用のuuidのみ）
- blank nodeは存在しない前提

**クロスドメインクローリング**:

- 取得したトリプルから他の名前空間のURIを検出
- 検出した名前空間に対して自動的に再帰的クローリングを実行
- W3C、Schema.org等の標準語彙は除外（`config.ini`の`[standard_vocabularies]`で設定可能）

**注**: 関連情報探索方式（`RelatedDataCrawler`）のソースコードは保持されていますが、現在は使用されていません。

## 設定

### config.ini

```ini
[server]
port = 8080

[graphdb]
base_url = http://fuseki:3030
dataset = /ds

[amqp]
# AMQP接続先（RDFPatch受信用）
url = amqp://guest:guest@rabbitmq:5672/
queue = rdfpatch_queue
timeout_sec = 30.0

[mqtt]
# MQTT通知設定
host = mosquitto
port = 1883

[crawler]
max_workers = 1              # シリアル実行（1スレッドのみ）
sparql_timeout_sec = 10.0
sparql_retry = 3
# ガードレール（コメントアウト=無制限）
# max_depth = 5
# max_triples = 10000

[design_support]
url = http://design-support-system:8080/api/notify
```

### 環境変数での上書き

以下の環境変数で設定を上書きできます：

- `PORT`: サーバーポート
- `FUSEKI_BASE_URL`: FusekiのベースURL
- `FUSEKI_DATASET`: Fusekiのデータセット名
- `AMQP_URL`: AMQP接続先URL
- `AMQP_QUEUE`: AMQP キュー名
- `AMQP_TIMEOUT_SEC`: AMQP タイムアウト
- `MQTT_HOST`: MQTTブローカーホスト
- `MQTT_PORT`: MQTTブローカーポート
- `CRAWLER_MAX_WORKERS`: クローリングスレッド数
- `CRAWLER_MAX_DEPTH`: 探索深さ上限
- `CRAWLER_MAX_TRIPLES`: 取得トリプル数上限
- `CRAWLER_MAX_DURATION_SEC`: クローリング総実行時間上限
- `CRAWLER_SPARQL_TIMEOUT_SEC`: SPARQL問い合わせタイムアウト
- `CRAWLER_SPARQL_RETRY`: SPARQL再試行回数
- `CRAWLER_MAX_QUEUE`: 探索キューの最大サイズ
- （削除）テストモード関連の環境変数は廃止しました
- `DESIGN_SUPPORT_URL`: 設計支援システムURL
- `REGISTRY_JSON_PATH`: ドメインアプリレジストリのJSON保存先パス（既定: `/tmp/domain_registry.json`）

## 起動方法

### 初回セットアップ

1. **環境変数ファイルを作成**

```bash
cd crawler-service
cp .env.example .env
```

2. **.envを編集**

必要に応じて設定を変更してください。詳細は[設定](#設定)セクションを参照。

### サービスの起動

crawler-serviceと依存サービスをまとめて起動できます。

```bash
# 全サービス起動
docker-compose up --build

# ログ確認
docker-compose logs -f
```

### サービスの停止

```bash
# 停止して削除
docker-compose down

# 停止のみ（データは保持）
docker-compose stop

# 再開
docker-compose start
```

### 接続情報

- **crawler-service**: http://localhost:8080/health
- **RabbitMQ Management**: http://localhost:15672 (guest/guest)
- **Fuseki UI**: http://localhost:3030
- **MQTT**: localhost:1884

Fusekiのデータセット `/ds` は `fuseki-init` により起動時に自動作成されます。

### 疎通確認（curl）

起動できたかを確認する最小手順です。

```bash
curl -X GET http://localhost:8080/health
```

## 使用方法

### API仕様

### POST /v1/api/query

外部システムからSPARQLクエリを発行するAPIです。

#### リクエスト

```json
{
  "query": "SELECT * WHERE { ?s ?p ?o }",
  "target": "http://domain-app.example.com/query"  // オプション
}
```

#### レスポンス

SPARQL JSON Results形式:

```json
{
  "head": {
    "vars": ["s", "p", "o"]
  },
  "results": {
    "bindings": [...]
  }
}
```

#### 動作

- **クエリ検証**: READ系（SELECT, CONSTRUCT, DESCRIBE, ASK）以外は 400 エラー
- **target なし**: Fuseki（キャッシュ）へクエリ
- **target あり**: 指定したSPARQLエンドポイントへクエリし、クローリングスレッドを起動
  - クエリ本文からseed URIを抽出できる場合のみクローリング開始
  - 差分受信登録を実施（未登録の場合）
- **設計支援システムへの通知**: 全クエリで実行（非同期）

#### エラーレスポンス

- `400 Bad Request`: クエリが不正（READ系以外）
- `502 Bad Gateway`: upstreamエラー
- `500 Internal Server Error`: 内部エラー

## ライセンス

- 本リポジトリはMITライセンスで提供されています。
- ソースコードおよび関連ドキュメントの著作権はIntentExchange株式会社に帰属します。

## 免責事項

- 本リポジトリの内容は予告なく変更・削除する可能性があります。
- 本リポジトリの利用により生じた損失及び損害等について、いかなる責任も負わないものとします。