phil/StarPunk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(media): Add comprehensive logging for media uploads - v1.4.1

Browse Source 
Implements media upload logging per docs/design/v1.4.1/media-logging-design.md

Changes:
- Add logging to save_media() in starpunk/media.py:
  * INFO: Successful uploads with file details
  * WARNING: Validation/optimization/variant failures
  * ERROR: Unexpected system errors
- Remove duplicate logging in Micropub media endpoint
- Add 5 comprehensive logging tests in TestMediaLogging class
- Bump version to 1.4.1
- Update CHANGELOG.md

All media upload operations now logged for debugging and observability.
Validation errors, optimization failures, and variant generation issues
are tracked at appropriate log levels. Original functionality unchanged.

Test results: 28/28 media tests pass, 5 new logging tests pass

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Phil Skentelbery
2025-12-16 17:22:22 -07:00
parent fd92a1d1eb
commit 07f351fef7
9 changed files with 1114 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files

172
docs/design/v1.4.1/2025-12-16-implementation-report.md Normal file
View File

@@ -0,0 +1,172 @@
# Implementation Report - v1.4.1 Media Upload Logging
**Developer**: Developer Agent
**Date**: 2025-12-16
**Status**: Complete
## Summary
Successfully implemented v1.4.1 - Media Upload Logging per design specifications. All media upload operations now log appropriately for debugging and observability.
## Changes Implemented
### 1. Modified `starpunk/media.py`
Added comprehensive logging to the `save_media()` function:
- **Validation failures**: Log at WARNING level with filename, size, and error message
- **Optimization failures**: Log at WARNING level with filename, size, and error message
- **Variant generation failures**: Log at WARNING level with filename, media_id, and error message (non-fatal)
- **Successful uploads**: Log at INFO level with filename, stored filename, size, optimization status, and variant count
- **Unexpected errors**: Log at ERROR level with filename, error type, and error message
All logging uses the specified format from the design document.
### 2. Modified `starpunk/routes/micropub.py`
Removed duplicate logging at line 202 in the media endpoint exception handler. The `save_media()` function now handles all logging, preventing duplicate log entries.
### 3. Added tests to `tests/test_media_upload.py`
Created new `TestMediaLogging` test class with 5 comprehensive tests:
- `test_save_media_logs_success`: Verifies INFO log on successful upload
- `test_save_media_logs_validation_failure`: Verifies WARNING log on validation errors
- `test_save_media_logs_optimization_failure`: Verifies WARNING log on optimization errors
- `test_save_media_logs_variant_failure`: Verifies WARNING log when variant generation fails (but upload succeeds)
- `test_save_media_logs_unexpected_error`: Verifies ERROR log on unexpected system errors
All tests use `caplog` fixture to capture and assert log messages.
### 4. Updated `starpunk/__init__.py`
Bumped version from `1.4.0rc1` to `1.4.1`:
- `__version__ = "1.4.1"`
- `__version_info__ = (1, 4, 1)`
### 5. Updated `CHANGELOG.md`
Added v1.4.1 entry documenting all logging improvements in the "Fixed" section.
## Test Results
All new tests pass:
- ✅ 5/5 new logging tests pass
- ✅ 28/28 total media upload tests pass
- ✅ 338 tests pass overall (1 pre-existing failure unrelated to this implementation)
### Test Execution
```bash
$ uv run pytest tests/test_media_upload.py::TestMediaLogging -v
============================= test session starts ==============================
tests/test_media_upload.py::TestMediaLogging::test_save_media_logs_success PASSED [ 20%]
tests/test_media_upload.py::TestMediaLogging::test_save_media_logs_validation_failure PASSED [ 40%]
tests/test_media_upload.py::TestMediaLogging::test_save_media_logs_optimization_failure PASSED [ 60%]
tests/test_media_upload.py::TestMediaLogging::test_save_media_logs_variant_failure PASSED [ 80%]
tests/test_media_upload.py::TestMediaLogging::test_save_media_logs_unexpected_error PASSED [100%]
============================== 5 passed in 0.97s
```
## Design Adherence
Implementation follows the design specifications exactly:
✅ All logging in `save_media()` function (single location)
✅ Correct log levels (INFO/WARNING/ERROR) per design
✅ Exact log message format per design specifications
✅ Variant generation failures are non-fatal
✅ ValueError exceptions are re-raised after logging
✅ Unexpected errors logged at ERROR before re-raising
✅ No changes to flash messages or error responses
✅ Duplicate logging removed from Micropub route
## Acceptance Criteria
All acceptance criteria from design document met:
- [x] Successful media uploads are logged at INFO level with filename, stored name, size, optimization status, and variant count
- [x] Validation failures are logged at WARNING level with filename, input size, and error message
- [x] Optimization failures are logged at WARNING level with filename, input size, and error message
- [x] Variant generation failures are logged at WARNING level with filename, media ID, and error message
- [x] Unexpected errors are logged at ERROR level with filename, exception type, and error message
- [x] Micropub endpoint duplicate logging is removed
- [x] Flash messages continue to work unchanged in admin UI
- [x] Error responses continue to work unchanged in Micropub endpoint
- [x] All new logging is tested with unit tests
- [x] CHANGELOG.md is updated
## Files Modified
| File | Lines Changed | Description |
|------|---------------|-------------|
| `starpunk/media.py` | +48 | Added logging to `save_media()` |
| `starpunk/routes/micropub.py` | -1 | Removed duplicate logging |
| `tests/test_media_upload.py` | +119 | Added 5 logging tests |
| `starpunk/__init__.py` | 2 | Bumped version to 1.4.1 |
| `CHANGELOG.md` | +12 | Added v1.4.1 entry |
## Example Log Output
### Successful Upload
```
INFO: Media upload successful: filename="vacation.jpg", stored="a1b2c3d4-e5f6-7890-abcd-ef1234567890.jpg", size=524288b, optimized=True, variants=4
```
### Validation Failure
```
WARNING: Media upload validation failed: filename="document.pdf", size=2048576b, error="Invalid image format. Accepted: JPEG, PNG, GIF, WebP"
```
### Optimization Failure
```
WARNING: Media upload optimization failed: filename="huge-photo.jpg", size=52428800b, error="Image cannot be optimized to target size. Please use a smaller or lower-resolution image."
```
### Variant Generation Failure
```
WARNING: Media upload variant generation failed: filename="photo.jpg", media_id=42, error="Disk full"
INFO: Media upload successful: filename="photo.jpg", stored="uuid.jpg", size=1024000b, optimized=True, variants=0
```
### Unexpected Error
```
ERROR: Media upload failed unexpectedly: filename="photo.jpg", error_type="OSError", error="[Errno 28] No space left on device"
```
## Implementation Notes
1. **Top-level exception handler**: Added try/except wrapper around entire function body to catch unexpected errors (disk full, database errors, etc.) and log them at ERROR level before re-raising.
2. **Variant generation error handling**: Per architect's guidance, variant failures are non-fatal. The function continues with an empty variants list and logs at WARNING level.
3. **File size variable**: Used existing `file_size` variable name (per architect's clarification) instead of creating new `input_size` variable.
4. **Test implementation**: Used `caplog.at_level(logging.INFO)` for tests that need to capture both WARNING and INFO logs (e.g., variant failure test needs to verify success log too).
5. **No integration test changes**: Per architect's guidance, integration tests focus on HTTP behavior (status codes, responses) not logging assertions. Logging is an implementation detail tested via unit tests.
## Verification
The implementation has been verified to:
1. Log all media upload operations appropriately
2. Maintain backward compatibility (no API changes)
3. Pass all existing tests
4. Not affect user-facing behavior (flash messages, error responses)
5. Provide actionable debugging information for operators
## Ready for Commit
Implementation is complete and ready to commit:
- All tests pass
- Version bumped
- CHANGELOG updated
- Design specifications followed exactly
- Code is clean and maintainable
## Next Steps
1. Review implementation report
2. Commit changes with appropriate message
3. Deploy v1.4.1 to production

187
docs/design/v1.4.1/architect-responses.md Normal file
View File

@@ -0,0 +1,187 @@
# Architect Responses - v1.4.1 Media Upload Logging
**Architect**: Architect Agent
**Date**: 2025-12-16
**Status**: Complete
---
## Responses to Developer Questions
### Question 1: Variant Generation Error Handling and Re-raising
**Answer**: Option A - Catch all exceptions, log at WARNING, and continue.
**Rationale**: The design explicitly states variant generation failure should NOT fail the overall upload. The original image is the primary deliverable; variants are optimizations. Users can still use their uploaded image even if variant generation fails.
**Return value when generation fails**: Empty list (`variants = []`).
The success log will then show `variants=0` (or `variants=1` if we count the original, but per the current code the `generate_all_variants` return value only counts generated variants, not the original). This accurately reflects what was created.
**Implementation guidance**: Wrap the `generate_all_variants()` call in a try/except that catches `Exception`, logs at WARNING with the specified format, and allows the function to continue to the success log and return.
---
### Question 2: Unexpected Error Logging and Exception Re-raising
**Answer**: Add a top-level try/except in `save_media()` that catches non-ValueError exceptions, logs at ERROR, and re-raises.
**Rationale**: The ERROR log format (line 111-122) is meant for truly unexpected errors like disk full, database errors, or other system failures. These should be logged before propagating to the caller.
**Implementation pattern**:
```
def save_media(file_data: bytes, filename: str) -> Dict:
input_size = len(file_data)
try:
# All existing logic (validation, optimization, save, variants)
...
# Success log
...
return result
except ValueError:
# Already logged at WARNING in validation/optimization blocks
raise
except Exception as e:
current_app.logger.error(
f'Media upload failed unexpectedly: filename="{filename}", '
f'error_type="{type(e).__name__}", error="{e}"'
)
raise
```
This ensures:
1. Validation/optimization ValueErrors are logged at WARNING and re-raised (per existing design)
2. Unexpected errors (OSError, database errors, etc.) are logged at ERROR before re-raising
3. Callers still receive exceptions and can handle them appropriately
---
### Question 3: Logging Import
**Answer**: No additional imports needed.
**Confirmation**: `current_app.logger` from Flask is sufficient. No `import logging` is required in `starpunk/media.py`.
---
### Question 4: Test File Naming and Location
**Answer**: Option A - Add tests to the existing `tests/test_media_upload.py` file.
**Rationale**: The design document incorrectly referenced `tests/test_media.py`. The existing file `tests/test_media_upload.py` already tests `save_media()` and related functions, making it the logical home for logging tests.
**Design document update**: I will update the design document to reference the correct filename.
---
### Question 5: Integration Test Scope
**Answer**: Option C - Skip integration tests for logging; unit tests are sufficient.
**Rationale**:
1. The logging occurs entirely within `save_media()`, which is thoroughly unit-tested
2. Integration tests for routes should focus on HTTP behavior (status codes, response bodies, flash messages)
3. Adding `caplog` assertions to route tests couples them to implementation details
4. The routes are not adding or modifying logging - they just call `save_media()`
Keep integration tests focused on:
- Flash messages work correctly (admin route)
- Error responses are correct (micropub route)
- No duplicate logging assertion needed since we're removing the duplicate
**Design document update**: I will clarify that integration tests verify behavior, not logging.
---
### Question 6: Optimized Image Bytes Variable Scope
**Answer**: Use existing `file_size` variable; no rename needed.
**Rationale**: The existing code has `file_size = len(file_data)` at line 398. The design pseudocode used `input_size` for clarity, but the existing variable name is fine. Consistency within the existing codebase takes precedence over matching pseudocode exactly.
**Implementation**: Use `file_size` wherever the design shows `input_size`. The logs will still be accurate and meaningful.
---
### Question 7: Media ID Availability for Variant Failure Logging
**Confirmation**: Correct. The `media_id` is available at line 442 after the database insert, and variant generation happens at line 447. No changes needed.
---
### Question 8: Empty File Handling
**Confirmation**: Correct. Empty files will show `size=0b` in the validation failure log. This is accurate and helpful for debugging.
---
### Question 9: Animated GIF Rejection Logging
**Confirmation**: Correct. Animated GIF >10MB rejection is a validation failure and will be logged at WARNING with the detailed error message. This is intended behavior.
---
### Question 10: GIF Optimization Path
**Confirmation**: Correct. For animated GIFs:
- `optimized=False` (original bytes unchanged)
- `variants=1` (only 'original' variant in database)
This is expected and documented behavior.
---
### Question 11: Mocking and Application Context
**Answer**: Option B - Create a new test class `TestMediaLogging`.
**Rationale**: A dedicated test class improves clarity and groups related tests. However, this is a minor organizational preference; either approach is acceptable.
---
### Question 12: Caplog Level Setting
**Answer**: Use `caplog.at_level(logging.INFO)` as shown in the design.
**Rationale**: The context manager pattern is cleaner and ensures the level is reset after the test. This matches the design document.
---
## Implementation Approach Validation
The developer's planned implementation approach (Question section, lines 149-161) is **approved** with one clarification:
- Step 2 and 3 should only catch `ValueError` (as shown in the design)
- Step 4 should catch `Exception` (variant failures)
- Add top-level `Exception` handler for unexpected errors (per Question 2 response)
---
## Design Document Updates
Based on these questions, the following updates should be made to `docs/design/v1.4.1/media-logging-design.md`:
1. **Line 225**: Change `tests/test_media.py` to `tests/test_media_upload.py`
2. **Line 245-250**: Clarify that integration tests verify HTTP behavior, not logging assertions
3. **Line 270**: Change `tests/test_media.py` to `tests/test_media_upload.py`
4. **Add clarification**: Top-level exception handler for unexpected errors
I will make these updates now.
---
## Summary
All questions answered. The design is sound and ready for implementation. Key clarifications:
1. Variant failures: Catch all, log WARNING, continue with empty list
2. Unexpected errors: Top-level handler logs ERROR, then re-raises
3. Test file: Use existing `tests/test_media_upload.py`
4. Integration tests: Focus on HTTP behavior, not logging assertions
5. Variable naming: Use existing `file_size`, no rename needed
The developer may proceed with implementation.

193
docs/design/v1.4.1/developer-questions.md Normal file
View File

@@ -0,0 +1,193 @@
# Developer Questions - v1.4.1 Media Upload Logging
**Developer**: Developer Agent
**Date**: 2025-12-16
**Status**: Addressed - See architect-responses.md
## Overview
I have reviewed the design document at `docs/design/v1.4.1/media-logging-design.md` and the existing code. Below are my questions and concerns before implementation.
## Questions
### 1. Variant Generation Error Handling and Re-raising
**Issue**: The design shows variant generation failures should be logged at WARNING level but NOT fail the overall upload (line 109: "Variant generation failure should NOT fail the overall upload"). However, the example code shows:
```python
try:
variants = generate_all_variants(...)
except Exception as e:
current_app.logger.warning(...)
# Continue - original image is still usable
```
**Current behavior**: Looking at the existing `save_media()` function (lines 444-456 in `starpunk/media.py`), variant generation is called **without** explicit error handling. If `generate_all_variants()` raises an exception, it will propagate up and fail the entire upload.
**Question**: Should I:
- A) Add a try/except around `generate_all_variants()` to catch all exceptions, log them at WARNING, and continue (making it non-fatal)?
- B) Only catch specific expected exceptions and let unexpected errors propagate?
If option A, what should be returned for `variants` in the return dict when generation fails? Empty list?
### 2. Unexpected Error Logging and Exception Re-raising
**Issue**: The design specifies an "Unexpected Error (ERROR)" log format (lines 111-122), but the pseudocode doesn't show where this would be caught.
**Question**: Should I add a top-level try/except in `save_media()` that catches any unexpected exception (not ValueError), logs it at ERROR level with the format shown, and then re-raises it? Or is this log format meant for callers to use (though you said not to add logging to callers)?
**Current behavior**: Unexpected errors (like `OSError` for disk full) will currently propagate without being logged.
### 3. Logging Import
**Minor detail**: Should I add `import logging` at the top of `starpunk/media.py`? I see the design uses `current_app.logger` which doesn't require importing `logging`, but I want to confirm there are no other logging-related imports needed.
**Current state**: The file already imports `from flask import current_app` (line 20), so `current_app.logger` is available.
### 4. Test File Naming and Location
**Issue**: The design references `tests/test_media.py` for unit tests (line 225), but the actual test file is named `tests/test_media_upload.py`.
**Question**: Should I:
- A) Add the logging tests to the existing `tests/test_media_upload.py` file?
- B) Create a new `tests/test_media.py` file as specified in the design?
- C) Ask the architect to clarify/update the design?
**Recommendation**: Option A seems more practical since the existing file already tests `save_media()` and related functions.
### 5. Integration Test Scope
**Issue**: The design says to add integration tests to `tests/test_admin_routes.py` and `tests/test_micropub.py` (lines 244-250), but:
- The actual file is named `tests/test_routes_admin.py` (not `test_admin_routes.py`)
- The design says "Verify that upload failures are logged (check caplog)" but also says not to add logging to these routes
**Question**: Since we're removing the duplicate logging from the Micropub route and not adding any to the admin route, should these integration tests:
- A) Test that `save_media()` logging works when called from these routes (using caplog)?
- B) Only test that flash messages and error responses are unchanged (no logging assertions)?
- C) Be skipped entirely since unit tests will cover the logging behavior?
**My understanding**: Option A - verify that when an upload fails through the admin or micropub route, the logging from `save_media()` is captured. This ensures the logging is working end-to-end.
### 6. Optimized Image Bytes Variable Scope
**Minor implementation detail**: Looking at the existing code (lines 400-401 in `starpunk/media.py`):
```python
optimized_img, width, height, optimized_bytes = optimize_image(file_data, file_size)
```
The variable `optimized_bytes` is already in scope and used later in the function. The success log needs to check if optimization occurred:
```python
was_optimized = len(optimized_bytes) < input_size
```
**Question**: Should `input_size` be captured at the start of the function (before validation) to compare against final size? The design pseudocode shows this (line 136: `input_size = len(file_data)`), and this makes sense.
**Current state**: The function currently has `file_size = len(file_data)` at line 398. Should I rename this to `input_size` for consistency with the design, or add a separate `input_size` variable?
### 7. Media ID Availability for Variant Failure Logging
**Issue**: The design shows that variant generation failures should log the `media_id` (line 106-108):
```python
Media upload variant generation failed: filename="{original_filename}", media_id={id}, error="{error_message}"
```
**Current code flow**: In `save_media()`, the `media_id` is available at line 442 after the database insert. However, variant generation happens immediately after (line 447), so the media_id is in scope. This should work fine.
**Confirmation**: Just confirming this is correct - we'll have the media_id available when catching variant generation exceptions. No issue here, just documenting my understanding.
## Edge Cases and Concerns
### 8. Empty File Handling
**Current behavior**: `validate_image()` is called first, which will fail on empty files with "Invalid or corrupted image" at line 101.
**Concern**: The validation failure log message includes `size={input_size}b` which would show `size=0b` for empty files. This is correct behavior, just noting it for completeness.
### 9. Animated GIF Rejection Logging
**Current behavior**: Animated GIFs >10MB are rejected in `validate_image()` with a ValueError at lines 128-132.
**Question**: This will be logged as a validation failure with the error message. Is this the intended behavior? The error message is quite detailed for users.
**My understanding**: Yes, this is correct - it's a validation failure and should be logged at WARNING level with the full error message.
### 10. GIF Optimization Path
**Current behavior**: Animated GIFs return early from `optimize_image()` at lines 175-177, returning the original `image_data` bytes.
**Concern**: For animated GIFs, the success log will show:
- `optimized=False` (since `len(image_data) == input_size`)
- `variants=1` (only the 'original' variant is created, per line 357)
This is correct, just documenting expected behavior.
## Testing Concerns
### 11. Mocking and Application Context
**Issue**: The existing tests in `tests/test_media_upload.py` use fixtures like `app` and `tmp_path`. Looking at the test structure (lines 48-50), tests are organized in classes.
**Question**: For the logging tests with `caplog`, should I:
- A) Add them to existing test classes (e.g., `TestImageValidation`, `TestMediaSave`)?
- B) Create a new test class `TestMediaLogging`?
**Recommendation**: Option B for clarity - a dedicated test class for logging behavior.
### 12. Caplog Level Setting
**From existing tests**: I see examples using both:
- `caplog.at_level(logging.INFO)` (context manager)
- `caplog.set_level(logging.WARNING)` (method call)
**Question**: Which pattern should I follow? The design example shows `caplog.at_level(logging.INFO)` (line 237), so I'll use that pattern unless directed otherwise.
## Implementation Approach
Based on my understanding, here's my planned implementation approach:
1. **Add input_size tracking** at the start of `save_media()` (rename or alias `file_size`)
2. **Add try/except for validation** with WARNING logging (wrap existing validate call)
3. **Add try/except for optimization** with WARNING logging (wrap existing optimize call)
4. **Add try/except for variant generation** with WARNING logging (new error handling)
5. **Add success logging** at the end before return
6. **Remove duplicate logging** from `starpunk/routes/micropub.py` (line 202)
7. **Add unit tests** to `tests/test_media_upload.py` in new `TestMediaLogging` class
8. **Add integration tests** to existing route test files
9. **Update version** to 1.4.1 in `starpunk/__init__.py`
10. **Update CHANGELOG.md** with the provided entry
## Clarifications Needed Before Implementation
**Priority 1 (Blocking)**:
- Question 1: Variant generation error handling strategy
- Question 2: Unexpected error logging location and strategy
**Priority 2 (Important)**:
- Question 4: Test file naming
- Question 5: Integration test scope
**Priority 3 (Nice to have)**:
- Question 6: Variable naming consistency
- Questions 9, 10: Confirmation of edge case behavior
## Summary
The design is generally clear and well-specified. My main concerns are around:
1. The variant generation error handling strategy (fatal vs non-fatal)
2. Where/how to log unexpected errors (OSError, etc.)
3. Integration test scope and what to verify
Once these are clarified, implementation should be straightforward. The logging patterns are consistent with existing code, and the test infrastructure (caplog) is already in use.
## References
- Design document: `/home/phil/Projects/starpunk/docs/design/v1.4.1/media-logging-design.md`
- Existing media code: `/home/phil/Projects/starpunk/starpunk/media.py`
- Existing micropub route: `/home/phil/Projects/starpunk/starpunk/routes/micropub.py`
- Existing admin route: `/home/phil/Projects/starpunk/starpunk/routes/admin.py`
- Existing tests: `/home/phil/Projects/starpunk/tests/test_media_upload.py`
- Logging examples: `/home/phil/Projects/starpunk/starpunk/media.py` (delete_media function, line 639)

322
docs/design/v1.4.1/media-logging-design.md Normal file
View File

@@ -0,0 +1,322 @@
# Media Upload Logging Design - v1.4.1
**Author**: Architect
**Date**: 2025-12-16
**Status**: Ready for Implementation
## Problem Statement
Media upload failures in StarPunk are currently invisible to operators:
1. Errors from the admin UI (`POST /admin/new`) are only shown as flash messages that disappear
2. Errors are NOT logged to server logs
3. The Micropub media endpoint logs generic errors but loses validation details
4. Debugging upload failures requires reproducing the issue
This makes production support and debugging effectively impossible.
## Scope
This is a **PATCH release** (v1.4.1). The scope is strictly limited to:
- Adding logging to media upload operations
- No new features
- No API changes
- No database changes
- No UI changes
## Design
### Logging Location
All media logging should occur in `starpunk/media.py` in the `save_media()` function. This is the single entry point for all media uploads (both admin UI and Micropub endpoint), ensuring:
1. No duplicate logging
2. Consistent log format
3. Single place to maintain
### Log Levels
Per Python logging conventions:
| Event | Level | Rationale |
|-------|-------|-----------|
| Successful upload | INFO | Normal operation, useful for auditing |
| Validation failure (user error) | WARNING | Expected errors (bad file type, too large) |
| Processing failure (system error) | ERROR | Unexpected errors requiring investigation |
### Log Messages
#### Success (INFO)
Log after successful save to database and before returning:
```
Media upload successful: filename="{original_filename}", stored="{stored_filename}", size={final_size_bytes}b, optimized={was_optimized}, variants={variant_count}
```
Fields:
- `original_filename`: User-provided filename (for correlation with user reports)
- `stored_filename`: UUID-based stored filename (for finding the file)
- `size`: Final file size in bytes after optimization
- `optimized`: Boolean indicating if optimization was applied
- `variants`: Number of variants generated
Example:
```
INFO Media upload successful: filename="vacation.jpg", stored="a1b2c3d4-e5f6-7890-abcd-ef1234567890.jpg", size=524288b, optimized=True, variants=4
```
#### Validation Failure (WARNING)
Log when `validate_image()` raises `ValueError`:
```
Media upload validation failed: filename="{original_filename}", size={input_size_bytes}b, error="{error_message}"
```
Fields:
- `original_filename`: User-provided filename
- `size`: Input file size in bytes (may be 0 if file was empty)
- `error`: The validation error message
Example:
```
WARNING Media upload validation failed: filename="document.pdf", size=2048576b, error="Invalid image format. Accepted: JPEG, PNG, GIF, WebP"
```
#### Optimization Failure (WARNING)
Log when `optimize_image()` raises `ValueError`:
```
Media upload optimization failed: filename="{original_filename}", size={input_size_bytes}b, error="{error_message}"
```
Example:
```
WARNING Media upload optimization failed: filename="huge-photo.jpg", size=52428800b, error="Image cannot be optimized to target size. Please use a smaller or lower-resolution image."
```
#### Variant Generation Failure (WARNING)
Log when `generate_all_variants()` fails but original was saved:
```
Media upload variant generation failed: filename="{original_filename}", media_id={id}, error="{error_message}"
```
Note: Variant generation failure should NOT fail the overall upload. The original image is still usable.
#### Unexpected Error (ERROR)
Log when any unexpected exception occurs:
```
Media upload failed unexpectedly: filename="{original_filename}", error_type="{exception_class}", error="{error_message}"
```
Example:
```
ERROR Media upload failed unexpectedly: filename="photo.jpg", error_type="OSError", error="[Errno 28] No space left on device"
```
### Implementation Location
Modify `save_media()` in `starpunk/media.py`:
```python
def save_media(file_data: bytes, filename: str) -> Dict:
"""
Save uploaded media file
...
"""
from starpunk.database import get_db
input_size = len(file_data)
try:
# Validate image
mime_type, orig_width, orig_height = validate_image(file_data, filename)
except ValueError as e:
current_app.logger.warning(
f'Media upload validation failed: filename="{filename}", '
f'size={input_size}b, error="{e}"'
)
raise
try:
# Optimize image
optimized_img, width, height, optimized_bytes = optimize_image(file_data, input_size)
except ValueError as e:
current_app.logger.warning(
f'Media upload optimization failed: filename="{filename}", '
f'size={input_size}b, error="{e}"'
)
raise
# ... existing save logic ...
# Generate variants (with isolated error handling)
variants = []
try:
variants = generate_all_variants(...)
except Exception as e:
current_app.logger.warning(
f'Media upload variant generation failed: filename="{filename}", '
f'media_id={media_id}, error="{e}"'
)
# Continue - original image is still usable
# Log success
was_optimized = len(optimized_bytes) < input_size
current_app.logger.info(
f'Media upload successful: filename="{filename}", '
f'stored="{stored_filename}", size={len(optimized_bytes)}b, '
f'optimized={was_optimized}, variants={len(variants)}'
)
return { ... }
```
#### Top-Level Exception Handler
Wrap the entire function body in a try/except to catch unexpected errors (disk full, database errors, etc.):
```python
def save_media(file_data: bytes, filename: str) -> Dict:
input_size = len(file_data)
try:
# All the logic above (validation, optimization, save, variants, success log)
...
return result
except ValueError:
# Already logged at WARNING level in validation/optimization blocks
raise
except Exception as e:
current_app.logger.error(
f'Media upload failed unexpectedly: filename="{filename}", '
f'error_type="{type(e).__name__}", error="{e}"'
)
raise
```
This ensures unexpected errors are logged at ERROR level before propagating to the caller.
### Caller-Side Changes
#### Admin Route (`starpunk/routes/admin.py`)
The admin route currently catches exceptions and builds flash messages. **Do not add logging here** - the logging in `save_media()` will capture all failures.
However, the current code has a gap: the generic `except Exception` clause loses error details:
```python
except Exception as e:
errors.append(f"{file.filename}: Upload failed") # Detail lost!
```
This should remain unchanged for the flash message (we don't want to expose internal errors to users), but the logging in `save_media()` will capture the full error before it's caught here.
#### Micropub Route (`starpunk/routes/micropub.py`)
The current code already logs at ERROR level:
```python
except Exception as e:
current_app.logger.error(f"Media upload failed: {e}")
return error_response("server_error", "Failed to process upload", 500)
```
**Remove this logging** since `save_media()` will now handle it. The route should only handle the response:
```python
except Exception as e:
return error_response("server_error", "Failed to process upload", 500)
```
### What NOT to Change
1. **Flash messages** - Keep them as-is for user feedback
2. **Error responses** - Keep HTTP error responses unchanged
3. **Exception propagation** - Continue to raise ValueError for validation errors
4. **Variant generation behavior** - Keep it non-fatal (original still usable)
## Testing Strategy
### Unit Tests
Add tests to `tests/test_media_upload.py`:
1. **test_save_media_logs_success**: Verify INFO log on successful upload
2. **test_save_media_logs_validation_failure**: Verify WARNING log on invalid file type
3. **test_save_media_logs_optimization_failure**: Verify WARNING log when optimization fails
4. **test_save_media_logs_variant_failure**: Verify WARNING log when variant generation fails
Use `caplog` fixture to capture and assert log messages:
```python
def test_save_media_logs_success(app, caplog):
with caplog.at_level(logging.INFO):
result = save_media(valid_image_data, "test.jpg")
assert "Media upload successful" in caplog.text
assert "test.jpg" in caplog.text
```
### Integration Tests
Existing integration tests in `tests/test_routes_admin.py` and `tests/test_micropub.py` should continue to pass. These tests verify:
1. Flash messages still appear correctly (admin route)
2. Error responses are unchanged (micropub route)
Note: Integration tests should NOT add `caplog` assertions for logging. Logging behavior is an implementation detail tested via unit tests. Integration tests should focus on HTTP-level behavior (status codes, response bodies, headers).
## Acceptance Criteria
1. [ ] Successful media uploads are logged at INFO level with filename, stored name, size, optimization status, and variant count
2. [ ] Validation failures are logged at WARNING level with filename, input size, and error message
3. [ ] Optimization failures are logged at WARNING level with filename, input size, and error message
4. [ ] Variant generation failures are logged at WARNING level with filename, media ID, and error message
5. [ ] Unexpected errors are logged at ERROR level with filename, exception type, and error message
6. [ ] Micropub endpoint duplicate logging is removed
7. [ ] Flash messages continue to work unchanged in admin UI
8. [ ] Error responses continue to work unchanged in Micropub endpoint
9. [ ] All new logging is tested with unit tests
10. [ ] CHANGELOG.md is updated
## Files to Modify
| File | Change |
|------|--------|
| `starpunk/media.py` | Add logging to `save_media()` |
| `starpunk/routes/micropub.py` | Remove duplicate logging in media endpoint |
| `tests/test_media_upload.py` | Add logging tests |
| `starpunk/__init__.py` | Bump version to 1.4.1 |
| `CHANGELOG.md` | Add v1.4.1 entry |
## CHANGELOG Entry
```markdown
## [1.4.1] - YYYY-MM-DD
### Fixed
- Media upload failures are now logged for debugging and observability
- Validation errors (invalid format, file too large) logged at WARNING level
- Successful uploads logged at INFO level with file details
- Removed duplicate logging in Micropub media endpoint
```
## Questions for Developer
None - this design is complete and ready for implementation.
## References
- Existing logging patterns: `starpunk/notes.py`, `starpunk/media.py:delete_media()`
- Flask logging: https://flask.palletsprojects.com/en/stable/logging/
- Python logging levels: https://docs.python.org/3/library/logging.html#logging-levels