Add safe native recording rename workflow

Makefile

@@ -38,7 +38,7 @@ LIBS += $(shell pkg-config --libs Magick++)
 CXXFLAGS += -DUSE_LIBMAGICKPLUSPLUS
 endif
 
-OBJS = $(PLUGIN).o serverthread.o tools.o info.o searchtimers.o channels.o events.o recordings.o remote.o timers.o changestate.o eventsstreamthread.o changestatetracker.o scraper2vdr.o statusmonitor.o osd.o jsonparser.o epgsearch.o wirbelscan.o webapp.o femon.o
+OBJS = $(PLUGIN).o serverthread.o tools.o info.o searchtimers.o channels.o events.o recordings.o recordingmutation.o recordinganalysis.o recordingmoveanalysis.o recordingrenameplan.o recordingrenamepreflight.o recordingpreflight.o recordingmovepreflight.o recordingpreview.o recordingmovepreview.o recordingrenamepreview.o recordingexecution.o recordingmoveexecution.o recordingvalidate.o recordingmovevalidate.o recordingrenamevalidate.o recordingmoveexecutor.o recordingmove.o recordingrename.o recordingtrashexecutor.o recordingtrash.o remote.o timers.o changestate.o eventsstreamthread.o changestatetracker.o scraper2vdr.o statusmonitor.o osd.o jsonparser.o epgsearch.o wirbelscan.o webapp.o femon.o
 CFGS = API.html
 
 all: $(SOFILE) i18n
@@ -55,8 +55,8 @@ $(DEPFILE): Makefile
 
 PODIR     = po
 I18Npo    = $(wildcard $(PODIR)/*.po)
-I18Nmo    = $(addsuffix .mo, $(foreach file, $(I18Npo), $(basename $(file))))
-I18Nmsgs  = $(addprefix $(DESTDIR)$(LOCDIR)/, $(addsuffix /LC_MESSAGES/vdr-$(PLUGIN).mo, $(notdir $(foreach file, $(I18Npo), $(basename $(file))))))
+I18Nmo    = $(addsuffix .mo, $(foreach file,$(I18Npo),$(basename $(file))))
+I18Nmsgs  = $(addprefix $(DESTDIR)$(LOCDIR)/, $(addsuffix /LC_MESSAGES/vdr-$(PLUGIN).mo, $(notdir $(foreach file,$(I18Npo),$(basename $(file))))))
 I18Npot   = $(PODIR)/$(PLUGIN).pot
 
 %.mo: %.po
@@ -72,9 +72,59 @@ $(I18Npot): $(wildcard *.cpp)
 $(I18Nmsgs): $(DESTDIR)$(LOCDIR)/%/LC_MESSAGES/vdr-$(PLUGIN).mo: $(PODIR)/%.mo
 	install -D -m644 $< $@
 
-.PHONY: i18n
+.PHONY: i18n test-recording-move-plan test-recording-move-analysis test-recording-move-preflight test-recording-move-execution-gate test-recording-rename-plan test-recording-rename-preflight
 i18n: $(I18Nmo) $(I18Npot)
 
+test-recording-move-plan:
+	$(CXX) -std=c++17 -Wall -Wextra \
+		recordingmutation.cpp \
+		tests/test_recording_move_plan.cpp \
+		-o /tmp/test_recording_move_plan
+	/tmp/test_recording_move_plan
+
+test-recording-move-analysis:
+	$(CXX) -std=c++17 -Wall -Wextra \
+		recordingmutation.cpp \
+		recordingmoveanalysis.cpp \
+		tests/test_recording_move_analysis.cpp \
+		-o /tmp/test_recording_move_analysis
+	/tmp/test_recording_move_analysis
+
+test-recording-move-preflight:
+	$(CXX) -std=c++17 -Wall -Wextra \
+		recordingmutation.cpp \
+		recordingmoveanalysis.cpp \
+		recordingmovepreflight.cpp \
+		tests/test_recording_move_preflight.cpp \
+		-o /tmp/test_recording_move_preflight
+	/tmp/test_recording_move_preflight
+
+test-recording-move-execution-gate:
+	$(CXX) -std=c++17 -Wall -Wextra \
+		recordingmutation.cpp \
+		recordingmoveanalysis.cpp \
+		recordingmoveexecution.cpp \
+		tests/test_recording_move_execution_gate.cpp \
+		-o /tmp/test_recording_move_execution_gate
+	/tmp/test_recording_move_execution_gate
+
+test-recording-rename-plan:
+	$(CXX) -std=c++17 -Wall -Wextra \
+		recordingrenameplan.cpp \
+		tests/test_recording_rename_plan.cpp \
+		-o /tmp/test_recording_rename_plan
+	/tmp/test_recording_rename_plan
+
+test-recording-rename-preflight:
+	$(CXX) -std=c++17 -Wall -Wextra \
+		recordingmutation.cpp \
+		recordingmoveanalysis.cpp \
+		recordingrenameplan.cpp \
+		recordingrenamepreflight.cpp \
+		tests/test_recording_rename_preflight.cpp \
+		-o /tmp/test_recording_rename_preflight
+	/tmp/test_recording_rename_preflight
+
 install-i18n: $(I18Nmsgs)
 
 $(SOFILE): $(OBJS)
@@ -94,12 +144,7 @@ dist: $(I18Npo) clean
 	@cp -a * $(TMPDIR)/$(ARCHIVE)
 	@-rm -rf $(TMPDIR)/$(ARCHIVE)/debian
 	@tar czf $(PACKAGE).tgz -C $(TMPDIR) $(ARCHIVE)
-	@-rm -rf $(TMPDIR)/$(ARCHIVE)
 	@echo Distribution package created as $(PACKAGE).tgz
 
 clean:
-	@-rm -f $(PODIR)/*.mo $(PODIR)/*.pot
-	@-rm -f $(OBJS) $(DEPFILE) *.so *.tgz core* *~ ._*
-
-archive:
-	git archive --format=tar.gz --prefix=vdr-plugin-restfulapi-${VERSION}/ --output=../vdr-plugin-restfulapi-${VERSION}.tar.gz master
+	@-rm -f $(PODIR)/*.mo $(PODIR)/*.pot $(OBJS) $(DEPFILE) $(SOFILE) *~

RECORDING_MOVE_API.md

@@ -0,0 +1,198 @@
+# Safe Native Recording Move API
+
+This document describes the safe recording move workflow implemented by the RESTfulAPI plugin.
+
+The implementation follows native VDR behavior. It does not stop playback, stop recordings, modify timers, cancel recording handler operations, or bypass VDR recording list updates.
+
+## Workflow
+
+Recording move uses a three-step optimistic-locking workflow:
+
+1. Preview the operation and obtain state fingerprints.
+2. Optionally validate that the fingerprints are still current.
+3. Execute the operation with the confirmed fingerprints.
+
+Preview and validation are read-only. They do not modify the recording, timers, playback state, filesystem, or VDR recording lists.
+
+## Path contract
+
+Both `file` and `target_file` are complete native VDR filesystem identities.
+
+Example:
+
+```text
+/srv/vdr/video/Example/2026-07-14.08.53.3-0.rec
+```
+
+The target must be absolute, must differ from the source, and must not already exist in the filesystem or VDR recording list.
+
+## Preview
+
+```http
+POST /recordings/move/preview.json
+Content-Type: application/json
+```
+
+Request:
+
+```json
+{
+  "file": "/srv/vdr/video/Example/2026-07-14.08.53.3-0.rec",
+  "target_file": "/srv/vdr/video/Archive/Example/2026-07-14.08.53.3-0.rec"
+}
+```
+
+Executable response:
+
+```json
+{
+  "executable": true,
+  "recording_file": "/srv/vdr/video/Example/2026-07-14.08.53.3-0.rec",
+  "target_file": "/srv/vdr/video/Archive/Example/2026-07-14.08.53.3-0.rec",
+  "constraints": [],
+  "blockers": [],
+  "warnings": [],
+  "steps": [
+    "move-recording",
+    "refresh-recordings",
+    "notify-change"
+  ],
+  "revision_recording_file": "/srv/vdr/video/Example/2026-07-14.08.53.3-0.rec",
+  "revision_target_file": "/srv/vdr/video/Archive/Example/2026-07-14.08.53.3-0.rec",
+  "revision_recordings_state": 123456789,
+  "revision_timers_state": 987654321
+}
+```
+
+## Validate
+
+```http
+POST /recordings/move/validate.json
+Content-Type: application/json
+```
+
+Request:
+
+```json
+{
+  "file": "/srv/vdr/video/Example/2026-07-14.08.53.3-0.rec",
+  "target_file": "/srv/vdr/video/Archive/Example/2026-07-14.08.53.3-0.rec",
+  "revision_recordings_state": "123456789",
+  "revision_timers_state": "987654321"
+}
+```
+
+Validation status values:
+
+- `ready`: source, target, recording state, and timer state still match the preview revision.
+- `conflict`: source, target, replay, handler, or timer state changed after preview.
+- `blocked`: the current state or policy does not allow execution.
+
+## Execute
+
+```http
+POST /recordings/move.json
+Content-Type: application/json
+```
+
+Request:
+
+```json
+{
+  "file": "/srv/vdr/video/Example/2026-07-14.08.53.3-0.rec",
+  "target_file": "/srv/vdr/video/Archive/Example/2026-07-14.08.53.3-0.rec",
+  "revision_recordings_state": "123456789",
+  "revision_timers_state": "987654321"
+}
+```
+
+Successful response:
+
+```json
+{
+  "status": "moved",
+  "recording_file": "/srv/vdr/video/Example/2026-07-14.08.53.3-0.rec",
+  "target_file": "/srv/vdr/video/Archive/Example/2026-07-14.08.53.3-0.rec",
+  "message": "Recording moved to the requested target."
+}
+```
+
+Idempotent retry after the source has already been moved to the requested target:
+
+```json
+{
+  "status": "already-moved",
+  "recording_file": "/srv/vdr/video/Example/2026-07-14.08.53.3-0.rec",
+  "target_file": "/srv/vdr/video/Archive/Example/2026-07-14.08.53.3-0.rec",
+  "message": "Recording is already present at the requested target."
+}
+```
+
+## Protected states
+
+The operation is blocked when safety cannot be established or VDR is actively using the recording:
+
+- `replay-active`
+- `recording-handler-busy`
+- `local-timer-active`
+- `remote-timer-active`
+- `unknown-recording-handler-state`
+- `unknown-local-timer-state`
+- `unknown-remote-timer-state`
+- `unknown-search-timer-state`
+
+Move-specific blockers include:
+
+- `move-target-missing`
+- `move-target-invalid`
+- `move-target-same-as-source`
+- `move-target-exists`
+
+The execution endpoint does not automatically resolve these states.
+
+## Execution behavior
+
+The executor:
+
+1. Revalidates the optimistic-locking revision.
+2. Acquires VDR timer and recording write locks.
+3. Rechecks source, target, replay, handler, recording control, and timer association.
+4. Uses the native VDR directory move helper.
+5. Verifies that the source disappeared and the target exists.
+6. Replaces the source identity with the target identity in the VDR recording list.
+7. Runs the native `recordingaction rename` hook.
+8. Forces video disk usage refresh and recording change notification.
+
+## HTTP status codes
+
+| Status | Meaning |
+|---|---|
+| `200` | The recording was moved or is already present at the requested target. |
+| `400` | Source, target, or required revision values are missing or invalid. |
+| `404` | The source recording disappeared before execution. |
+| `409` | Source, target, recording, replay, handler, or timer state changed after preview. |
+| `423` | The operation is blocked by the current VDR state or policy. |
+| `500` | The native VDR mutation or postcondition verification failed. |
+| `501` | The requested HTTP method is not supported. |
+
+## Verified integration behavior
+
+The following cases were verified against a running VDR installation on July 15, 2026:
+
+- preview: `200`, executable, no filesystem mutation
+- validate: `200 ready`, expected and current revisions identical
+- missing revision: `400`
+- stale revision: `409`
+- unsupported method: `501`
+- completed 285 MB recording: `200 moved`
+- source directory removed and target directory present
+- old VDR recording identity absent and new identity present
+- native directory creation and rename logged by VDR
+- native `vdr-recordingaction rename` hook executed
+- immediate identical retry: `200 already-moved`
+- reverse move through the same preview, validate, and execute workflow: `200 moved`
+- final VDR recording list restored to the original identity
+
+## Design boundary
+
+This API moves a recording to one explicit native VDR filesystem identity. It is not a generic file manager, does not copy recordings, and does not silently stop active VDR operations.