s3_direct_multipart_upload 0.1.0

data/doc/api.yml

@@ -0,0 +1,256 @@
+openapi: 3.0.0
+info:
+  title: S3 ダイレクトマルチパートアップロード API
+  version: 0.1.0
+  description: |
+    このエンジンが提供するアップロードセッション API の OpenAPI 定義。
+    既存ログインセッション（Cookie 認証）を前提とし、JSON ベースでやり取りする。
+    セキュリティ上の注意:
+      - `upload_session_id` は推測困難なトークンとし、ユーザー単位でアクセス制御する。
+      - presigned URL は短寿命とし、レスポンスがログ等に残らないよう配慮する。
+      - S3 キー（`key_prefix`）は Active Storage と同様にランダムな名前空間を使い、ユーザー入力を直接含めない。
+      - ファイルサイズ・MIME のバリデーションをサーバーで必須化し、許可された添付種類のみに限定する。
+paths:
+  /s3_direct_multipart_uploads:
+    post:
+      summary: アップロードセッションの開始
+      description: |
+        マルチパートアップロードセッションを開始し、S3 presigned URL を払い出す。ファイルそのものの情報だけを受け取り、
+        attachable との紐付けは後続のフォーム POST で行う。認証済みエンタープライズユーザーのみ利用可能。
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UploadSessionRequest'
+      responses:
+        '201':
+          description: 作成成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UploadSessionResponse'
+        '400':
+          description: パラメータ不正（サイズ超過や未対応 attachment など）
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '404':
+          description: 参照できないリソース、または権限不足
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+  /s3_direct_multipart_uploads/{upload_session_id}/parts:
+    post:
+      summary: パートアップロード完了の報告
+      description: |
+        クライアントが S3 へ PUT 完了したパート番号と `ETag` をサーバーへ通知する。
+        サーバーはアップロードセッションにパート情報を保存する。
+      parameters:
+        - name: upload_session_id
+          in: path
+          required: true
+          schema:
+            type: string
+          description: "POST <mount_path>/s3_direct_multipart_uploads で払い出したセッション ID"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/ReportPartRequest'
+      responses:
+        '202':
+          description: 受領成功
+        '404':
+          description: セッションが見つからない、もしくは期限切れ
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '422':
+          description: パート番号や ETag が不正
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+  /s3_direct_multipart_uploads/{upload_session_id}/complete:
+    post:
+      summary: アップロード完了の確定
+      description: |
+        全パートのアップロードが完了した後に呼び出し、S3 の `CompleteMultipartUpload` を実行する。
+        成功すると UploadSession に結合済みファイルのメタ情報が保存され、後続のフォーム POST で任意のレコードに紐付けできる。
+      parameters:
+        - name: upload_session_id
+          in: path
+          required: true
+          schema:
+            type: string
+      requestBody:
+        required: false
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                checksum:
+                  type: string
+                  description: クライアント側で計算した全体ファイルのチェックサム（任意）
+      responses:
+        '200':
+          description: 完了し、Blob が作成された
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CompleteResponse'
+        '409':
+          description: まだ全パートが揃っていない、またはすでに完了済み
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '404':
+          description: セッションが見つからない
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '422':
+          description: パラメータ不正
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+components:
+  schemas:
+    UploadSessionRequest:
+      type: object
+      required:
+        - upload
+      properties:
+        upload:
+          type: object
+          required:
+            - filename
+            - byte_size
+            - content_type
+          properties:
+            filename:
+              type: string
+              example: session.mp4
+            byte_size:
+              type: integer
+              description: バイト単位の想定ファイルサイズ
+              example: 2147483648
+            content_type:
+              type: string
+              example: video/mp4
+            chunk_size:
+              type: integer
+              description: 希望するチャンクサイズ（バイト）。省略時はサーバーが推奨値を返す。5MB 未満のファイルは単一パートとして扱われ、`chunk_size` は `byte_size` に揃えられる。
+              example: 10485760
+            checksum:
+              type: string
+              description: オプションの全体ファイルチェックサム（Base64 など）
+    UploadSessionResponse:
+      type: object
+      properties:
+        upload_session:
+          type: object
+          required:
+            - id
+            - upload_id
+            - bucket
+            - key_prefix
+            - chunk_size
+            - part_limit
+            - parts
+          properties:
+            id:
+              type: string
+              example: usn_1234567890
+            upload_id:
+              type: string
+              description: AWS S3 の UploadId
+              example: v1lUZWY4akp...==
+            bucket:
+              type: string
+              example: ir-live-tmp
+            key_prefix:
+              type: string
+              description: S3 オブジェクトキーの共通プレフィックス
+              example: uploads/log_order_items/123/20250301_abcd
+            chunk_size:
+              type: integer
+              description: サーバーが推奨するチャンクサイズ（バイト）
+              example: 10485760
+            part_limit:
+              type: integer
+              description: S3 制約上の最大パート数（通常 10000）
+              example: 10000
+            parts:
+              type: array
+              description: 各パートごとの presigned URL
+              items:
+                type: object
+                required:
+                  - part_number
+                  - url
+                  - expires_in
+                properties:
+                  part_number:
+                    type: integer
+                    minimum: 1
+                  url:
+                    type: string
+                    format: uri
+                  expires_in:
+                    type: integer
+                    description: URL 有効期限（秒）
+                    example: 900
+                  headers:
+                    type: object
+                    additionalProperties:
+                      type: string
+                    description: 署名付き URL に対して設定すべきヘッダー（必要な場合のみ）
+    ReportPartRequest:
+      type: object
+      required:
+        - part
+      properties:
+        part:
+          type: object
+          required:
+            - part_number
+            - etag
+          properties:
+            part_number:
+              type: integer
+              minimum: 1
+            etag:
+              type: string
+              description: S3 が返却した `ETag`
+    CompleteResponse:
+      type: object
+      properties:
+        upload_session:
+          type: object
+          properties:
+            id:
+              type: string
+            status:
+              type: string
+              description: セッション状態
+              example: completed
+            upload_id:
+              type: string
+              description: S3 UploadId（クライアント再利用用）
+    ErrorResponse:
+      type: object
+      required:
+        - error
+      properties:
+        error:
+          type: string

data/doc/api_dev.yml

@@ -0,0 +1,111 @@
+openapi: 3.0.0
+info:
+  title: S3DirectMultipartUpload 開発用 API
+  version: 0.1.0
+  description: |
+    development/test 環境限定の開発ユーティリティ API。
+    - Disk + stub 環境で presigned PUT を受け、パートをローカルに保存
+    - completed セッションを結合し単一ファイルをダウンロード
+components:
+  schemas:
+    ErrorResponse:
+      type: object
+      properties:
+        error:
+          type: string
+      required:
+        - error
+paths:
+  /s3_direct_multipart_upload/dev/storage/uploads/s3_direct/{date}/{session_uuid}/{filename}:
+    put:
+      summary: 開発用ストレージへのパート PUT（Disk + stub 用）
+      description: |
+        presigned URL で署名された PUT を受け取り、`tmp/s3_direct_multipart_upload/<object_key>.parts/<partNumber>` に保存する。
+        development/test 以外では 404。
+      parameters:
+        - name: date
+          in: path
+          required: true
+          schema:
+            type: string
+            pattern: '^\d{8}$'
+          description: YYYYMMDD のディレクトリ部分
+        - name: session_uuid
+          in: path
+          required: true
+          schema:
+            type: string
+          description: アップロードセッション UUID
+        - name: filename
+          in: path
+          required: true
+          schema:
+            type: string
+          description: 保存するファイル名
+        - name: uploadId
+          in: query
+          required: true
+          schema:
+            type: string
+        - name: partNumber
+          in: query
+          required: false
+          schema:
+            type: integer
+        - name: expires_at
+          in: query
+          required: true
+          schema:
+            type: integer
+          description: Unix 時刻（秒）
+        - name: signature
+          in: query
+          required: true
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/octet-stream:
+            schema:
+              type: string
+              format: binary
+      responses:
+        '200':
+          description: 保存成功。ETag をヘッダで返却。
+        '403':
+          description: 署名不正または期限切れ
+        '404':
+          description: 非 dev/test 環境
+  /s3_direct_multipart_upload/dev/storage/{upload_session_id}/download:
+    get:
+      summary: 結合済みファイルのダウンロード（開発限定）
+      description: |
+        completed セッションのみ許可。Disk 環境ではパートを結合して `tmp/s3_direct_multipart_upload/<object_key>` を返却。
+        S3 環境では `get_object` で取得。非 dev/test は 404。
+      parameters:
+        - name: upload_session_id
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: 結合済みファイルを返却
+          content:
+            application/octet-stream:
+              schema:
+                type: string
+                format: binary
+        '404':
+          description: セッションなし、または非 dev/test
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+        '422':
+          description: 未完了、欠損、結合失敗
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'

data/lib/generators/s3_direct_multipart_upload/install/install_generator.rb

@@ -0,0 +1,14 @@
+require "rails/generators"
+
+module S3DirectMultipartUpload
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+      desc "Engine のマイグレーションをホストへコピーする"
+
+      def copy_migrations
+        rake("s3_direct_multipart_upload:install:migrations")
+      end
+    end
+  end
+end

data/lib/s3_direct_multipart_upload/engine.rb

@@ -0,0 +1,16 @@
+module S3DirectMultipartUpload
+  class Engine < ::Rails::Engine
+    isolate_namespace S3DirectMultipartUpload
+
+    config.parent_controller = "::ApplicationController"
+
+    config.generators do |g|
+      g.test_framework :rspec
+      g.orm :active_record
+    end
+
+    rake_tasks do
+      load root.join("lib/tasks/s3_direct_multipart_upload_tasks.rake")
+    end
+  end
+end

data/lib/s3_direct_multipart_upload/version.rb

@@ -0,0 +1,3 @@
+module S3DirectMultipartUpload
+  VERSION = "0.1.0"
+end

data/lib/s3_direct_multipart_upload.rb

@@ -0,0 +1,9 @@
+require "s3_direct_multipart_upload/version"
+require "s3_direct_multipart_upload/engine"
+require "aws-sdk-s3"
+
+module S3DirectMultipartUpload
+  def self.table_name_prefix
+    "s3_direct_multipart_"
+  end
+end

data/lib/tasks/s3_direct_multipart_upload_tasks.rake

@@ -0,0 +1,15 @@
+namespace :s3_direct_multipart_upload do
+  namespace :install do
+    desc "Engine のマイグレーションをホストアプリへコピーする"
+    task migrations: :environment do
+      from = ENV["FROM"]
+      ENV["FROM"] = "s3_direct_multipart_upload"
+      begin
+        Rake::Task["railties:install:migrations"].invoke
+      ensure
+        Rake::Task["railties:install:migrations"].reenable
+        ENV["FROM"] = from
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,247 @@
+--- !ruby/object:Gem::Specification
+name: s3_direct_multipart_upload
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Logmi, Inc.
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-12-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: aws-sdk-s3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.143'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.143'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7.2'
+- !ruby/object:Gem::Dependency
+  name: combustion
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: committee-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: json_schemer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+- !ruby/object:Gem::Dependency
+  name: openapi_parser
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.3'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rails-omakase
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: simplecov-console
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.26'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.26'
+description: Rails アプリに組み込み、認証・セッションをホストに委譲したまま presigned URL を返すエンジン。
+email:
+- develop@logmi.co.jp
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- AGENTS.md
+- CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
+- MIT-LICENSE
+- OPERATIONS.md
+- README.md
+- SPEC.md
+- app/controllers/s3_direct_multipart_upload/application_controller.rb
+- app/controllers/s3_direct_multipart_upload/dev/storage_controller.rb
+- app/controllers/s3_direct_multipart_upload/dev/storage_downloads_controller.rb
+- app/controllers/s3_direct_multipart_upload/upload_completions_controller.rb
+- app/controllers/s3_direct_multipart_upload/upload_parts_controller.rb
+- app/controllers/s3_direct_multipart_upload/upload_sessions_controller.rb
+- app/models/s3_direct_multipart_upload/upload_session.rb
+- app/models/s3_direct_multipart_upload/upload_session_part.rb
+- app/services/s3_direct_multipart_upload/dev/storage.rb
+- config/initializers/s3_direct_dev.rb
+- config/routes.rb
+- config/storage/development.yml
+- config/storage/test.yml
+- db/migrate/20251113090000_create_s3_direct_multipart_upload_tables.rb
+- doc/api.yml
+- doc/api_dev.yml
+- lib/generators/s3_direct_multipart_upload/install/install_generator.rb
+- lib/s3_direct_multipart_upload.rb
+- lib/s3_direct_multipart_upload/engine.rb
+- lib/s3_direct_multipart_upload/version.rb
+- lib/tasks/s3_direct_multipart_upload_tasks.rake
+homepage: https://github.com/logmi/s3_direct_multipart_upload
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/logmi/s3_direct_multipart_upload
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: S3 へのダイレクトマルチパートアップロード API を提供する mountable engine
+test_files: []