Koha-clms/t
Martin Renvoize b75d07acd5
Bug 40811: Implement dual API for file transports with simplified auto-management
This patch implements a dual API design for Koha::File::Transport, providing
both a simplified auto-managing API and a traditional explicit API for maximum
flexibility and ease of use.

DUAL API DESIGN
===============

Simplified API (Recommended):
  - Automatic connection management (no connect/disconnect needed)
  - Flexible per-operation directory control via options hashref
  - Stateless operations safe for concurrent usage

  Example:
    $transport->upload_file($local, $remote, { path => '/custom/' });
    $transport->download_file($remote, $local);  # Uses download_directory
    $transport->list_files({ path => '/incoming/' });

Traditional API (Explicit Control):
  - Manual connection/directory management when needed
  - Stateful directory operations via change_directory()
  - Ideal for multiple operations in the same directory

  Example:
    $transport->change_directory('/work/');
    $transport->upload_file($local, 'file1.txt');
    $transport->upload_file($local, 'file2.txt');
    my $files = $transport->list_files();

The APIs can be mixed - calling change_directory() explicitly switches to
manual mode and disables auto-management for subsequent operations.

STANDARDIZED TEMPLATE METHOD PATTERN
=====================================

All transport methods now follow a consistent pattern with clear separation
between public API (parent class) and protocol implementation (subclasses).

Public methods in Koha::File::Transport:
  - connect()          → Resets directory state, calls _connect()
  - disconnect()       → Resets directory state, calls _disconnect()
  - change_directory() → Sets manual mode flag, calls _change_directory()
  - upload_file()      → Manages connection/directory, calls _upload_file()
  - download_file()    → Manages connection/directory, calls _download_file()
  - list_files()       → Manages connection/directory, calls _list_files()
  - rename_file()      → Ensures connection, calls _rename_file()

Subclass responsibilities (SFTP/FTP/Local):
  - Implement _connect() - Protocol-specific connection logic
  - Implement _disconnect() - Protocol-specific disconnection logic
  - Implement _change_directory() - Protocol-specific directory change
  - Implement _upload_file() - Protocol-specific upload logic
  - Implement _download_file() - Protocol-specific download logic
  - Implement _list_files() - Protocol-specific listing logic
  - Implement _rename_file() - Protocol-specific rename logic
  - Implement _is_connected() - Protocol-specific connection check

Test plan:
  prove t/db_dependent/Koha/File/Transports.t

Signed-off-by: Kyle M Hall <kyle@bywatersolutions.com>
Signed-off-by: Tomás Cohen Arazi <tomascohen@theke.io>
Signed-off-by: Lucas Gass <lucas@bywatersolutions.com>
2026-01-21 15:28:17 -07:00
..
Acquisition
…
Biblio Bug 40163: (follow-up) Fix wrong GNU links and update test 2025-09-24 09:25:04 -06:00
Budgets
…
Circulation Bug 40163: (follow-up) Fix wrong GNU links and update test 2025-09-24 09:25:04 -06:00
External
…
Koha Bug 40943: Fix t/Koha/Script.t 2025-11-07 07:43:52 -07:00
Number
…
SIP Bug 40163: (follow-up) Fix wrong GNU links and update test 2025-09-24 09:25:04 -06:00
Search Bug 40680: Fix t tests 2025-12-01 08:34:01 -07:00
Serials Bug 37796: Pass correct publication date when generating the next serial form the serial collection page 2025-12-17 13:24:17 -07:00
Template Bug 40163: (follow-up) Fix wrong GNU links and update test 2025-09-24 09:25:04 -06:00
Test Bug 40404: Remove diag from t/Test/Mock/Logger.t 2025-07-18 11:10:01 -06:00
cypress Bug 41615: Fix Licenses_spec.ts 2026-01-16 14:07:13 -07:00
data Bug 41032: Fix Open Fifth missing in plugin repos config 2025-11-26 10:40:25 -07:00
db_dependent Bug 40811: Implement dual API for file transports with simplified auto-management 2026-01-21 15:28:17 -07:00
edi_testfiles
…
etc
…
lib Bug 39522: Ignore the whole file for tidy 2026-01-12 10:53:33 -07:00
mock_templates/intranet-tmpl/prog Bug 41177: Add aria-disabled to breadcrumbs 2025-11-18 06:56:52 -07:00
00-check-atomic-updates.t Bug 40163: (follow-up) Fix wrong GNU links and update test 2025-09-24 09:25:04 -06:00
00-load.t Bug 40163: (follow-up) Fix wrong GNU links and update test 2025-09-24 09:25:04 -06:00
00-merge-conflict-markers.t Bug 40163: (follow-up) Fix wrong GNU links and update test 2025-09-24 09:25:04 -06:00
00-testcritic.t
…
00-valid-xml.t Bug 40163: (follow-up) Fix wrong GNU links and update test 2025-09-24 09:25:04 -06:00
Auth.t Bug 40163: (follow-up) Fix wrong GNU links and update test 2025-09-24 09:25:04 -06:00
AuthoritiesMarc_MARC21.t Bug 40680: Fix t tests 2025-12-01 08:34:01 -07:00
AuthoritiesMarc_UNIMARC.t Bug 40680: Fix t tests 2025-12-01 08:34:01 -07:00
Barcodes_EAN13.t
…
Barcodes_annual.t
…
Barcodes_hbyymmincr.t
…
Barcodes_incremental.t
…
Biblio.t Bug 40163: (follow-up) Fix wrong GNU links and update test 2025-09-24 09:25:04 -06:00
Biblio2.t
…
Breeding.t Bug 40017: (follow-up) Update GNU license link 2025-10-22 07:42:53 -06:00
Budgets.t
…
Charset.t Bug 40163: (follow-up) Fix wrong GNU links and update test 2025-09-24 09:25:04 -06:00
Circulation_barcodedecode.t Bug 40163: (follow-up) Fix wrong GNU links and update test 2025-09-24 09:25:04 -06:00
ClassSortRoutine.t
…
ClassSortRoutine_Dewey.t Bug 40680: Fix t tests 2025-12-01 08:34:01 -07:00
ClassSortRoutine_Generic.t Bug 40680: Fix t tests 2025-12-01 08:34:01 -07:00
ClassSortRoutine_LCC.t Bug 40680: Fix t tests 2025-12-01 08:34:01 -07:00
ClassSource.t
…
Context.t Bug 40163: (follow-up) Fix wrong GNU links and update test 2025-09-24 09:25:04 -06:00
Contract.t
…
CookieManager.t Bug 40163: (follow-up) Fix wrong GNU links and update test 2025-09-24 09:25:04 -06:00
Creators.t Bug 40680: Fix t tests 2025-12-01 08:34:01 -07:00
DateUtils.t
…
EdiInvoice.t
…
Edifact.t Bug 40391: Add unit tests for GIR:LSL support in EDI 2026-01-12 10:53:29 -07:00
Ediorder.t
…
Ediordrsp.t
…
Form_MessagingPreferences.t Bug 34776: Add unit tests for sub restore_form_values 2025-06-30 08:30:51 -06:00
HtmlTags.t
…
ImportBatch.t Bug 40163: (follow-up) Fix wrong GNU links and update test 2025-09-24 09:25:04 -06:00
Installer_PerlModules.t
…
ItemCirculationAlertPreference.t
…
Koha_MetadataRecord.t Bug 40163: (follow-up) Fix wrong GNU links and update test 2025-09-24 09:25:04 -06:00
Koha_SearchEngine_Elasticsearch_Browse.t Bug 40163: (follow-up) Fix wrong GNU links and update test 2025-09-24 09:25:04 -06:00
Koha_Template_Plugin_HtmlId.t Bug 40163: (follow-up) Fix wrong GNU links and update test 2025-09-24 09:25:04 -06:00
Koha_Template_Plugin_Koha.t Bug 40163: (follow-up) Fix wrong GNU links and update test 2025-09-24 09:25:04 -06:00
Koha_Util_FrameworkPlugin.t
…
Koha_Util_MARC.t Bug 40163: (follow-up) Fix wrong GNU links and update test 2025-09-24 09:25:04 -06:00
Koha_XSLT_HTTPS.t Bug 40163: (follow-up) Fix wrong GNU links and update test 2025-09-24 09:25:04 -06:00
Labels.t Bug 40680: Fix t tests 2025-12-01 08:34:01 -07:00
Labels_split_Regex.t Bug 40680: Fix t tests 2025-12-01 08:34:01 -07:00
Labels_split_ccn.t Bug 40163: (follow-up) Fix wrong GNU links and update test 2025-09-24 09:25:04 -06:00
Labels_split_ddcn.t Bug 40680: Fix t tests 2025-12-01 08:34:01 -07:00
Labels_split_lccn.t Bug 40680: Fix t/Labels* 2025-12-01 08:34:00 -07:00
Languages.t Bug 40163: (follow-up) Fix wrong GNU links and update test 2025-09-24 09:25:04 -06:00
Logger.t Bug 40163: (follow-up) Fix wrong GNU links and update test 2025-09-24 09:25:04 -06:00
Makefile.t Bug 40527: Add SECURITY.md to ignored list in MakeFile.t 2025-10-09 16:47:28 -06:00
Members_Messaging.t
…
OpenLibrarySearch.t Bug 40163: (follow-up) Fix wrong GNU links and update test 2025-09-24 09:25:04 -06:00
Output.t Bug 40163: (follow-up) Fix wrong GNU links and update test 2025-09-24 09:25:04 -06:00
Output_JSONStream.t
…
Patroncards.t
…
Patroncards_Batch.t
…
Patroncards_Lib.t
…
Patroncards_Patroncard.t
…
Patroncards_Profile.t
…
Patroncards_Template.t
…
RecordProcessor.t Bug 40163: (follow-up) Fix wrong GNU links and update test 2025-09-24 09:25:04 -06:00
Ris.t
…
SMS.t Bug 40680: Fix t tests 2025-12-01 08:34:01 -07:00
Scheduler.t
…
Scrubber.t Bug 39860: Update scrubber profile and add Scrubber.t test 2025-11-03 14:13:47 -07:00
Search.t Bug 40163: (follow-up) Fix wrong GNU links and update test 2025-09-24 09:25:04 -06:00
Search_PazPar2.t
…
SimpleMARC.t
…
SuggestionEngine.t
…
SuggestionEngine_AuthorityFile.t Bug 40163: (follow-up) Fix wrong GNU links and update test 2025-09-24 09:25:04 -06:00
TmplToken.t
…
Token.t Bug 40163: (follow-up) Fix wrong GNU links and update test 2025-09-24 09:25:04 -06:00
template_filters.t Bug 40163: (follow-up) Fix wrong GNU links and update test 2025-09-24 09:25:04 -06:00
timezones.t
…