History

binarybeach 9fb1ad44cd binarybeachio: presigned PUT for uploads (R2/B2 don't implement PostObject) == WHY (KEEP THIS — IT'S WHY THE FORK EXISTS) == Vanilla Plane's upload flow uses AWS S3 PostObject (presigned POST + multipart/form-data + signed-policy-document). Cloudflare R2 AND Backblaze B2 — the two most common self-host S3-compatible backends — both return HTTP 501 NotImplemented for PostObject. Empirically verified 2026-04-30 against B2 s3.us-west-004.backblazeb2.com from inside Plane's own prod api container, replicating Plane's exact boto3 call: PUT against B2: 200 OK POST against B2: 501 NotImplemented "This API call is not supported." POST against R2: 501 NotImplemented (failure that started this thread) The error code is `NotImplemented` (not `SignatureDoesNotMatch` etc), meaning the server rejects the verb itself — no boto3 config, addressing- style flag, or signature variant fixes it. Tested both path-style and virtual-hosted-style URLs against B2; both fail identically for POST. This patch rewrites the upload flow to use presigned PUT, which is universally supported (R2, B2, AWS S3 native, MinIO, Wasabi, etc). == WHAT (FIVE-FILE BACKEND, FIVE-FILE FRONTEND) == Backend: * apps/api/plane/settings/storage.py — S3Storage.generate_presigned_post now mints a presigned PUT URL via generate_presigned_url(HttpMethod="PUT"). Method name kept for caller compat. Response shape: {url, method: "PUT", fields: {Content-Type, key}}. * apps/api/plane/utils/openapi/responses.py — example response updated. * apps/api/plane/tests/unit/settings/test_storage.py — 2 tests updated to assert the new boto3 call. Frontend: * packages/types/src/file.ts — TFileSignedURLResponse.upload_data adds optional method?: "PUT" \| "POST"; drops AWS POST-form-data fields. * packages/services/src/file/helper.ts — generateFileUploadPayload now returns a TFileUploadRequest descriptor (url+method+body+headers) that dispatches on method. POST branch kept for upstream parity but the fork backend never emits POST. * packages/services/src/file/file-upload.service.ts + apps/web/core/services/file-upload.service.ts — uploadFile signature changes from (url, FormData, progress?) to (payload, progress?). * 5 caller sites updated (apps/web/core/services/file.service.ts x3, issue_attachment.service.ts x1, sites-file.service.ts x1). == TRADEOFFS ACCEPTED == * Lost: signed `content-length-range` enforcement at the storage layer. Server-side validation in the API view still rejects oversized requests with 413 before minting the URL, so a determined client could only over-upload by misreporting size, capped at the bucket's own size limit. * Different request shape on the wire (PUT with raw binary body vs POST with multipart form). Externally invisible to users. == ROLLBACK == If this becomes a maintenance nightmare: git revert <this-commit-sha> # rebuild + push images, swap compose tags, redeploy After revert, uploads will only work against backends that implement PostObject (MinIO, AWS S3 native). R2 and B2 will return 501 again. == FULL DECISION RECORD == binarybeachio repo: docs/features/storage-upload-flow.md Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>		2026-04-30 17:56:52 -10:00
..
__init__.py	[SILO-1026] feat: add estimates external API endpoints (#8664 )	2026-03-30 15:30:02 +05:30
auth.py	chore: add copyright (#8584 )	2026-01-27 13:54:22 +05:30
decorators.py	[SILO-1026] feat: add estimates external API endpoints (#8664 )	2026-03-30 15:30:02 +05:30
examples.py	[SILO-1026] feat: add estimates external API endpoints (#8664 )	2026-03-30 15:30:02 +05:30
hooks.py	chore: add copyright (#8584 )	2026-01-27 13:54:22 +05:30
parameters.py	[SILO-1026] feat: add estimates external API endpoints (#8664 )	2026-03-30 15:30:02 +05:30
README.md	[WEB-4045] feat: restructuring of the external APIs for better maintainability (#7477 )	2025-07-25 00:17:05 +05:30
responses.py	binarybeachio: presigned PUT for uploads (R2/B2 don't implement PostObject)	2026-04-30 17:56:52 -10:00

README.md

OpenAPI Utilities Module

This module provides a well-organized structure for OpenAPI/drf-spectacular utilities, replacing the monolithic openapi_spec_helpers.py file with a more maintainable modular approach.

Structure

plane/utils/openapi/
├── __init__.py          # Main module that re-exports everything
├── auth.py              # Authentication extensions
├── parameters.py        # Common OpenAPI parameters
├── responses.py         # Common OpenAPI responses
├── examples.py          # Common OpenAPI examples
├── decorators.py        # Helper decorators for different endpoint types
└── hooks.py            # Schema processing hooks (pre/post processing)

Usage

Import Everything (Recommended for backwards compatibility)

from plane.utils.openapi import (
    asset_docs,
    ASSET_ID_PARAMETER,
    UNAUTHORIZED_RESPONSE,
    # ... other imports
)

Import from Specific Modules (Recommended for new code)

from plane.utils.openapi.decorators import asset_docs
from plane.utils.openapi.parameters import ASSET_ID_PARAMETER
from plane.utils.openapi.responses import UNAUTHORIZED_RESPONSE

Module Contents

auth.py

APIKeyAuthenticationExtension - X-API-Key authentication
APITokenAuthenticationExtension - Bearer token authentication

parameters.py

Path parameters: WORKSPACE_SLUG_PARAMETER, PROJECT_ID_PARAMETER, ISSUE_ID_PARAMETER, ASSET_ID_PARAMETER
Query parameters: CURSOR_PARAMETER, PER_PAGE_PARAMETER

responses.py

Auth responses: UNAUTHORIZED_RESPONSE, FORBIDDEN_RESPONSE
Resource responses: NOT_FOUND_RESPONSE, VALIDATION_ERROR_RESPONSE
Asset responses: PRESIGNED_URL_SUCCESS_RESPONSE, ASSET_UPDATED_RESPONSE, etc.
Generic asset responses: GENERIC_ASSET_UPLOAD_SUCCESS_RESPONSE, ASSET_DOWNLOAD_SUCCESS_RESPONSE, etc.

examples.py

FILE_UPLOAD_EXAMPLE, WORKSPACE_EXAMPLE, PROJECT_EXAMPLE, ISSUE_EXAMPLE

decorators.py

workspace_docs() - For workspace endpoints
project_docs() - For project endpoints
issue_docs() - For issue/work item endpoints
asset_docs() - For asset endpoints

hooks.py

preprocess_filter_api_v1_paths() - Filters API v1 paths
postprocess_assign_tags() - Assigns tags based on URL patterns
generate_operation_summary() - Generates operation summaries

Migration Status

✅ FULLY COMPLETE - All components from the legacy openapi_spec_helpers.py have been successfully migrated to this modular structure and the old file has been completely removed. All imports have been updated to use the new modular structure.

What was migrated:

✅ All authentication extensions
✅ All common parameters and responses
✅ All helper decorators
✅ All schema processing hooks
✅ All examples and reusable components
✅ All asset view decorators converted to use new helpers
✅ All view imports updated to new module paths
✅ Legacy file completely removed

Files updated:

plane/api/views/asset.py - All methods use new @asset_docs helpers
plane/api/views/project.py - Import updated
plane/api/views/user.py - Import updated
plane/api/views/state.py - Import updated
plane/api/views/intake.py - Import updated
plane/api/views/member.py - Import updated
plane/api/views/module.py - Import updated
plane/api/views/cycle.py - Import updated
plane/api/views/issue.py - Import updated
plane/settings/common.py - Hook paths updated
plane/api/apps.py - Auth extension import updated

Benefits

Better Organization: Related functionality is grouped together
Easier Maintenance: Changes to specific areas only affect relevant files
Improved Discoverability: Clear module names make it easy to find what you need
Backwards Compatibility: All existing imports continue to work
Reduced Coupling: Import only what you need from specific modules
Consistent Documentation: All endpoints now use standardized helpers
Massive Code Reduction: ~80% reduction in decorator bloat using reusable components