Skip to content

Drive のファイル

Drive のファイルのアップロード・一覧・本文の更新と配信、タスクへの添付と本文からの参照

概要

テナントの利用者が Drive にファイルをアップロードし、一覧・更新・削除・ダウンロードする機能である。Markdown の本文に書いた KEY-N をタスクに結び付け、タスクへ手動で添付することもできる。アクセスの規則とストレージはDrive の概要に書き、判断の理由は Drive の決定の記録に集める。フォルダはフォルダと共有、容量はクォータ、プロジェクトのドキュメント画面はドキュメントに書く。

振る舞い

一覧

GET /v1/tenants/{tenant_id}/drive/files のクエリは次のとおりである。total は絞り込み後の件数である。

クエリ 型 既定 内容
folder_id UUID? フォルダで絞る。省略時はルート
mime_type string? MIME タイプの前方一致。text/markdown は text/markdown で始まる MIME(text/markdown; charset=… など)にも一致し、text/ のように末尾 / なら種別全体に一致する
q string? ファイル名の部分一致(ILIKE、大文字小文字を区別しない)。200 文字を超えると 400
sort string created_at_desc created_at_desc / name_asc / updated_at_desc。それ以外は 400。同順位は id 昇順
limit u32 50 取得件数。1..=200 に補正する。0 は 1、200 超は 200 になる
offset u32 0 オフセット

mime_type と q の % _ \ は字義どおりに扱い、LIKE のワイルドカードにしない。

アップロード

POST /v1/tenants/{tenant_id}/drive/files は multipart/form-data を受け取り、作成した DriveFile を 201 Created で返す。

フィールド 必須 内容
file 必須 ファイルのバイナリ
name 任意 表示名。省略時は元ファイル名で、どちらも無ければ 400
folder_id 任意 アップロード先フォルダの UUID

処理と制限の規則は次のとおりである。

  • フィールドの順序は問わない。file はストリームのままストレージへ流し、DB への登録は全パートを読み終えてから行う。登録に失敗したらストレージから消す
  • folder_id が file より前に届いた場合だけ、本文を流す前にフォルダの存在と書き込み権限を確かめて早く落とす
  • mime_type は、ソースコードの拡張子の上書き表(.ts など)、申告された Content-Type、ファイル名からの推定の順で決める
  • 最大ファイルサイズは UPLOAD_MAX_SIZE_MB(既定 100 MB)である。ファイル本体に対する上限で、ちょうどのサイズは受理する
  • リクエスト本文全体には、multipart の境界とヘッダーの分として 64 KiB を足した上限を掛ける
  • MIME タイプは全種類を許可する
  • 空ファイル、file パートなし、file パートが 2 つ以上は 400 Bad Request を返す

S3 では次の順に処理する。

  1. クライアントが POST /v1/tenants/{tenant_id}/drive/files(multipart)を送る
  2. バックエンドが multipart のストリームを受信する
  3. object_store で単一 PUT または multipart upload を実行する
  4. DB に drive_files の行を登録する。storage_key のみを保持する
  5. 応答に /v1/drive/files/{id}/content を url として組み立てて返す

名前の変更と移動

PATCH /v1/tenants/{tenant_id}/drive/files/{id} は name で名前を変更し、folder_id に UUID を渡すとそのフォルダへ移動する。folder_id の省略は配置を維持し、明示的な null はドライブ直下へ移動する。移動元・移動先の権限が必要で、移動に合わせて project_id も更新する。

本文の更新

PUT /v1/tenants/{tenant_id}/drive/files/{id}/content は { "content": "更新後の本文" } を受け取り、更新後の DriveFile を 200 OK で返す。

  • 対象は text/*、+json / +xml、JSON・JavaScript・YAML などの許可されたテキスト系 MIME である。対象外は 400 Bad Request を返す
  • 空文字列は許可する
  • UTF-8 のバイト数がファイルサイズ上限を超える場合、または差し替え後のテナント使用量がクォータを超える場合は 413 を返す
  • 新しいストレージキーへ保存してから DB を更新し、成功後に旧キーの削除を試みる

If-Match ヘッダーで楽観ロックできる。

  • 値は DriveFile.etag(ダブルクォート込み)をそのまま渡す
  • カンマ区切りの複数指定はどれか 1 つの一致で通り、* は常に一致する
  • 弱い ETag(W/"...")は W/ を外して比べる(TASK-336)
  • 一致しなければ 412 Precondition Failed(precondition-failed)を返し、本文は変えない
  • 比較はファイル行のロック取得後に行うので、同じ ETag を持った並行更新は片方だけが通り、もう片方は 412 になる
  • ヘッダーを省略した場合は無条件に上書きする(後勝ち)
  • 応答の etag は更新後の値である

ETag

DriveFile.etag は全ファイル API の応答に載る本文の ETag である。値はダブルクォート込みで、ETag ヘッダーと同じ文字列である。

行の状態 値
content_hash あり "sha256:<content_hash>"(強い ETag)。例は "sha256:2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae"
content_hash なし(導入前の行) "ts:<updated_at の Unix ミリ秒>-<size>"

本文の更新で updated_at が変わるので、導入前の行も If-Match で楽観ロックできる。本文を一度更新するとハッシュの形式に切り替わる。名前変更・移動では content_hash は変わらず、ハッシュ形式の ETag も変わらない。

配信

GET /v1/drive/files/{id}/content は本文を 200 OK で返す。?token={share_token} を付けると公開リンクのトークンで配信する。誰が取得できるかはDrive の認可の節に書く。

  • Content-Type を mime_type から設定する
  • Content-Disposition: attachment を常に設定し、ブラウザ上で同一オリジンのコンテンツとして実行させない
  • API 共通ミドルウェアが X-Content-Type-Options: nosniff を全応答に設定し、宣言した Content-Type 以外への MIME sniffing を禁止する
  • ストレージバックエンドの get_stream() でストリーミング配信し、メモリに全展開しない
  • ETag(DriveFile.etag と同じ値)と Last-Modified(updated_at を RFC 7231 の HTTP-date で秒精度)を付ける
  • If-None-Match が現在の ETag に一致すれば 304 Not Modified を本文なしで返し、304 にも ETag を付ける。ストレージは読まない。カンマ区切りの複数指定と * も可で、弱い ETag は W/ を外して比べる
  • If-Modified-Since は解釈しない

タスクへの添付

Drive のファイルは既存のタスクへ添付できる。添付は中間の行の作成・削除で、解除しても Drive のファイル本体は削除しない。

  • 添付できるのは同じテナントの一般ファイル、または対象タスクと同じプロジェクトのファイルである。別テナント・別プロジェクトのファイルは 403 Forbidden を返す
  • 同じファイルの二重添付は 409 Conflict を返す
  • 添付の解除は、添付を作成した利用者またはテナントオーナーに限る
  • 添付には由来 source(manual / body)があり、応答にも載る
  • 本文から付いた body の行へ POST すると manual に昇格して 200 OK を返す
  • body の行の DELETE は 409 Conflict を返す。本文を編集して参照を外す

規則の全体はタスク拡張のファイル添付に書く。

本文からのタスク参照

mime_type が text/markdown のファイルは、アップロード(POST .../drive/files)と本文の更新(PUT .../drive/files/{id}/content)のたびに本文の KEY-N を拾い、task_attachments へ source = 'body' で結び付ける。DB の更新と同じトランザクションで行う。名前変更・移動では本文を読み直さない。

抽出と結び付け先の規則は次のとおりである。

  • 結び付けは write:task を持つ場合だけ行う。セッションは常に持つ。write:drive だけの PAT では保存そのものは通し、同期を飛ばして既存の body 行にも触れない
  • 抽出は GitHub 連携と同じ service::forge::task_refs を使う。キーは大小文字不問で、Closes などのキーワードは無視する
  • 拾う前にフェンスコードブロック(``` / ~~~)とインラインコードの中身を落とす。閉じられていないフェンスは末尾まで落とす。インラインコードは行内でだけ対にする
  • 解決はファイルのテナント内のプロジェクトだけで行う。見つからない参照・削除済みタスクは捨てる
  • 結び付け先は手動の添付と同じ範囲である。テナント一般ファイル(project_id が NULL)はテナント内のどのプロジェクトのタスクにも結ぶ。プロジェクトファイルは同じプロジェクトのタスクにだけ結び、別プロジェクトの参照はリンクにせず黙って捨てる
  • 結び付けるのは、保存した利用者が入れるプロジェクトのタスクだけである。テナントオーナーは全プロジェクトに入れる。入れないものは黙って捨てる
  • 1 ファイルあたり、本文に現れた順で最初の 200 件の一意な参照までとする。解決できない参照も数える。200 件に達した時点で走査を止め、超えた分は捨てる

行の更新の規則は次のとおりである。

  • 今回の集合にあって行が無ければ body で作る。manual の行は書き換えない。今回の集合に無い body の行は消し、manual の行は残す
  • 消すのも、保存した利用者が入れるプロジェクトの body 行と削除済みタスクの行だけである。入れないプロジェクトへの body 行は残す
  • プロジェクトファイルから別プロジェクトのタスクへの body 行は、保存者が入れるかに関わらず消す
  • ファイルをプロジェクトのフォルダへ移すと、移動と同じトランザクションで、移動先のプロジェクトの外のタスクへの body 行を消す。PATCH .../files/{id} の folder_id と、フォルダの移動で配下の project_id が変わる場合の両方が対象である。manual の行と、テナント一般のフォルダへ移した場合の行は残す

GET /v1/tenants/{tenant_id}/drive/files/{id}/tasks は、ファイルに結び付いたタスク(manual と body の両方)を返す。呼び出し側が入れないプロジェクトのタスクと削除済みタスクは含めない。

データ

drive_files の列は次のとおりである。

列 型 制約 説明
id UUID PK
name VARCHAR NOT NULL ファイルの表示名(元ファイル名)
size BIGINT NOT NULL バイト数
mime_type VARCHAR NOT NULL application/octet-stream など
storage_type VARCHAR(16) NOT NULL Rust 側では enum。s3 または local
storage_key VARCHAR NOT NULL ストレージ固有のキー(UUID v4)。S3 の key またはローカルの相対パス
tenant_id UUID NOT NULL, FK tenants CASCADE
project_id UUID NULL 可, FK projects CASCADE フォルダの project_id を非正規化した値。ファイルのフォルダ移動時に再設定する
uploader_id UUID NOT NULL, FK users
folder_id UUID NULL 可, FK drive_folders SET NULL
created_at TIMESTAMPTZ NOT NULL DEFAULT now()
updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
content_hash VARCHAR(64) NULL 可 本文の SHA-256(hex)。アップロードと本文の更新で設定し、名前変更・移動では変えない。導入より前の行は backfill せず NULL のまま

project_id がセットされているときは folder_id も非 NULL でなければならない。DB の CHECK 制約(project_id IS NULL OR folder_id IS NOT NULL)と entity の before_save の両方で強制する。url の列は持たず、API の応答を作るときに URL を組み立てる。

列の定義は m20260520000000_initial_schema.rs、content_hash は m20261016005000_drive_files_content_hash.rs、task_attachments.source は m20261016010000_task_attachments_source.rs にある。

API

ファイルのエンドポイントは次のとおりである。

メソッド パス 説明
GET /v1/tenants/{tenant_id}/drive/files ファイルの一覧
POST /v1/tenants/{tenant_id}/drive/files ファイルのアップロード
GET /v1/tenants/{tenant_id}/drive/files/{id} ファイルのメタデータの取得
PATCH /v1/tenants/{tenant_id}/drive/files/{id} ファイルの更新(名前・フォルダ移動)
PUT /v1/tenants/{tenant_id}/drive/files/{id}/content 編集可能なテキストファイルの本文の更新
DELETE /v1/tenants/{tenant_id}/drive/files/{id} ファイルの削除
GET /v1/tenants/{tenant_id}/drive/files/{id}/tasks ファイルに結び付いたタスクの一覧
GET /v1/drive/files/{id}/content ファイルの内容の配信(ローカル・S3 プロキシ)
GET /v1/drive/files/{id}/content?token={token} 公開リンクのトークンによるファイルの配信

タスク添付のエンドポイントは次のとおりである。

メソッド パス スコープ 説明
GET /v1/tenants/{tenant_id}/projects/{project_id}/tasks/{id}/attachments read:task 添付の一覧
POST /v1/tenants/{tenant_id}/projects/{project_id}/tasks/{id}/attachments write:task { "drive_file_id": "uuid" } を添付する
DELETE /v1/tenants/{tenant_id}/projects/{project_id}/tasks/{id}/attachments/{attachment_id} write:task 添付を解除する

認可

アクセスの規則とエンドポイントごとのスコープはDrive の認可の節に書く。このページに固有の規則は次のとおりである。

操作 誰が スコープ
添付の解除 添付を作成した利用者またはテナントオーナー write:task
結び付いたタスクの一覧 メタデータの取得(GET .../drive/files/{id})と同じ判定を通る人。閲覧できなければ 403 / 404 read:drive と read:task
body 行の同期 保存した利用者 write:task がなければ同期を飛ばす

画面

タスク詳細の添付欄(TaskAttachments.vue)から Drive のファイルを添付する。OpenAPI クライアント用の定義と PAT のスコープ表示がある。

入力欄への貼り付け

本文の入力欄にファイルを貼り付ける(Ctrl+V / ⌘V)と、Drive へアップロードして本文に 1 行を入れる。

項目 内容
対象の入力欄 タスクの説明、タスク作成ダイアログの説明、ドキュメントの本文、コメントの入力欄、コメントの編集
保存先 入力欄があるプロジェクトのルートフォルダ。タスクの添付と同じ場所で、読める人はプロジェクトのメンバーである
上限 貼り付け専用の上限は無い。サーバーの UPLOAD_MAX_SIZE_MB と容量に従う
複数のファイル 1 回の貼り付けのファイルを並行でアップロードし、貼り付けた順に 1 行ずつ入れる

クリップボードにファイルがあり、text/plain と text/html の少なくとも片方が空のときだけファイルとして扱う。表計算や文書のアプリのように文字と HTML と画像を同時に載せる貼り付けは、文字として貼る。

本文に入る行は次のとおりである。URL は API の相対パス /v1/drive/files/{id}/content で、web は描画するときに /api を前に足す。

ファイル 本文に入る行 表示
MIME タイプが image/ で始まる、または拡張子が heic heif ![名前](URL) 画像
拡張子が mp4 mov webm m4v ![名前](URL) 動画のプレイヤー
拡張子が mp3 wav m4a ogg caf aac ![名前](URL) 音声のプレイヤー
それ以外 [名前](URL) ダウンロードのリンク

名前に含まれる Markdown の記号(\ [ ] * ` < & ~ と、語の端の _)は \ を前に付けて入れ、名前が強調・取り消し線・タグとして解釈されないようにする。

描画の規則は次のとおりである。

  • 書き換えるのは、URL が /v1/drive/files/{UUID}/content に完全一致する画像とリンクだけである。クエリやパスが続くもの、絶対 URL は書き換えない
  • 動画と音声は、画像の記法の名前(alt)の拡張子で見分ける。本文の URL には拡張子も MIME タイプも無い。拡張子の大文字と小文字は区別しない。名前から拡張子を消すと画像として描く
  • プレイヤーは自動再生しない
  • ブラウザが画像・動画・音声を読み込めなかったときは、その場でダウンロードのリンクに替える。HEIC は Safari 以外で、.mov は中身のコーデックによって表示できないことがある
  • リンクの中に置いた画像([![名前](URL)](リンク先))は URL を替えるだけで、プレイヤーにもダウンロードのリンクにもしない
  • ダウンロードのリンクには download 属性を付ける

アップロードの間と失敗時の扱いは次のとおりである。

  • アップロードの間は、貼り付けた位置に「アップロード中…」とファイル名を表示する。この表示は本文に含まれず、下書きにも保存にも入らない
  • アップロードの間は、その入力欄の送信・保存・作成を止める。表示の「取り消し」でアップロードを中断でき、中断すると送信・保存・作成をまた行える
  • 終わると、表示があった位置に行を入れる。その間に前後へ文字を入力していても位置は追従する
  • 失敗すると、同じ位置に理由と「再試行」「取り消し」を表示する。複数のうち一部だけ失敗したときは、成功した行だけを入れ、失敗したファイルだけを再試行の対象に残す
  • 入力欄を閉じる、別のタスクやスレッドへ切り替える、本文が外から差し替わる、表示を含む範囲を消す(元に戻す操作で消える場合を含む)、のいずれかで進行中のアップロードを中断し、結果を捨てる。送信・保存・作成はまた行える
  • 行の入れ替え(Alt+↑ / Alt+↓)と前後の字の入れ替え(Ctrl+T)では中断しない。表示は元の行の同じ位置に付いていく

失敗の理由は次の文言で表示する。

条件 文言
0 バイトのファイル 空のファイルは貼り付けできません
ルートフォルダの取得に失敗(通信の切断を含む) 保存先を読み込めませんでした
プロジェクトにルートフォルダが無い プロジェクトの保存先が見つかりません
413(サイズまたは容量の超過) ファイルがサイズ上限または保存容量を超えています
それ以外の失敗(通信の切断を含む) ファイルをアップロードできませんでした

未実装と既知の制限

  • 貼り付けたファイルは、本文から行を消しても、結果を捨てた場合でも Drive に残る
  • 貼り付けたファイルはタスクの添付にならない
  • アップロードの間に行の入れ替えを元に戻す操作をすると、表示のある行が消されて入れ直され、アップロードを中断することがある
  • 配信が Range リクエストに対応していない(TASK-565)。対応するまで、Safari は動画と音声を再生できずダウンロードのリンクに替わり、他のブラウザでも未読み込みの位置へシークできない
  • 貼り付けたファイルを変換しない。HEIC の画像や HEVC の動画は、表示できないブラウザではダウンロードのリンクになる
  • 画像のサムネイル生成が無い
  • ファイルの全文検索が無い
  • Drive のページ、ファイルブラウザ、クォータ、共有の画面が無い
  • 個別削除は DB の削除後のストレージエラーを無視する。孤児オブジェクトの扱いはDrive の未実装と既知の制限に書く

ファイルブラウザの導入時の設計

ページもコンポーネントもまだ無い。以下は導入時の設計で、URL は URL 仕様に合わせた予定のものである。

URL 内容
/{tenant}/drive ドライブのトップ(ルートフォルダ)
/{tenant}/drive/{folder_id} フォルダ内

上部にパンくず、左にフォルダツリーと新規フォルダのボタン、右に検索欄、アップロード、表示切り替え、ファイル一覧を置く。

ドライブ画面の配置。上部にパンくず、左にフォルダツリー、右に検索欄とファイル一覧を置く

コンポーネントの構成は次のとおりである。

コンポーネント ファイル 説明
DrivePage src/pages/@tenant/drive/+Page.vue ドライブ全体
DriveFolderPage src/pages/@tenant/drive/@folderId/+Page.vue フォルダ内
DriveSidebar src/components/drive/DriveSidebar.vue フォルダツリー
DriveFileGrid src/components/drive/DriveFileGrid.vue ファイル一覧(グリッド)
DriveFileList src/components/drive/DriveFileList.vue ファイル一覧(リスト)
DriveUploadButton src/components/drive/DriveUploadButton.vue ドラッグ&ドロップ対応
DriveFileCard src/components/drive/DriveFileCard.vue ファイルカード(グリッド用)
DriveFileDetail src/components/drive/DriveFileDetail.vue 詳細パネル(サイドシート)

主な操作は次のとおりである。

  • アップロードは、ボタンのクリックまたはエリアへのドラッグ&ドロップで行い、プログレスバーを表示する
  • フォルダの作成は、サイドバーの「+ 新しいフォルダ」ボタンからインラインで入力する
  • ファイルの詳細は、ファイルカードのクリックで右サイドシートに表示し、URL をコピーできる
  • 削除は、右クリックメニューまたは詳細パネルの削除ボタンから確認ダイアログを経て行う

Type to search…

↑↓ navigate↵ selectEsc close