Add support for alternative ProtocolFragments and Profiles

Current Situation

• YADE releases 1.x offer support for use of Alternative ProtocolFragments. with the source and target of a transfer profile They are triggered if the connection or authentication intially fails. Alternative ProtocolFragments can use a transfer protocol that is different from the standard protocol. This is useful, for example to fall back from use of SFTP to FTP.
• YADE releases 2.x do not offer the fallback option to Alternative ProtocolFragments. This is indicated with dismissal of YADE-650.
• YADE releases 2.x offer from TransferOptions the RetryOnConnectionError option which allows to specify the number of retries and interval between retries.

Desired Behavior

• YADE 2.x should offer use of Alternative ProtocolFragments from the following scope
  • An Alternative ProtocolFragment can be specified with the ProtocolFragment.
  • The Alternative ProtocolFragment can reference some other Alternative ProtocolFragment. The YADE will follow the chain of alternatives until the same ProtocolFragment is indicated.

• YADE 2.x should offer use of Alternative Profiles from the following scope:
  • The YADE CLI Client and YADE JITL Job are added the alternative_profile argument.
  • Use of an alternative profile is triggerd by errors during initial connection or authentication before a file transfer.
  • The option allows using file transfer protocols from the alternative profile that are different to the original profile.

Maintainer Note

• Protocol Fragment Alternatives
  • Protocol fragment alternatives define fallback protocol fragments that are considered only during the initial connection establishment.
    • Alternatives are evaluated only if the current protocol fragment cannot establish a connection.
      • If RetryOnConnectionError is configured, the current protocol fragment is retried according to the configured retry policy before the next alternative is evaluated.
    • They are not used after a connection has been established and therefore do not apply to reconnects or failures that occur during data transfer.
  • The order of the configured alternative elements determines the order in which alternatives are evaluated.
    • If an alternative protocol fragment defines its own alternatives, they are evaluated recursively.
    • To prevent circular references and duplicate processing, each referenced protocol fragment is evaluated at most once during the resolution process. If a protocol fragment has already been processed, it is skipped.
    • If RetryOnConnectionErrors is configured, each protocol fragment is retried according to the configured retry policy before the next alternative is evaluated.
    • Evaluation stops as soon as a connection has been established successfully.
    • The protocol fragment that established the connection is used for the subsequent file transfer.
  • Jump Host and Protocol Fragment Alternatives
    • A JumpFragment supports SFTPFragmentAlternatives according to the behavior described above.
    • If the Source or Target protocol fragment defines alternatives, the connection to an alternative protocol fragment is established from the Jump Host.
      • Consequently, any references to local resources (for example, ConfigurationFiles, CredentialStore, local key files, or similar resources) are resolved on the Jump Host.
      • These resources must therefore be available on the Jump Host at the configured locations.
  • Example: Alternative Evaluation
    • Given the following relationships:
      • A -> alternatives: B, C
      • B -> alternative: D
      • C -> no alternatives
      • D -> no alternatives
    • The evaluation order is: A, B, D, C
      • If D were also listed as an alternative of A, it would still be evaluated only once.

• Profile alternative_profile
  • The Profile alternative_profile defines a fallback profile that is considered only during the initial connection establishment.
  • They are not used for reconnect attempts or for failures that occur after a connection has already been established, including failures during data transfer.
    • Alternative profiles are evaluated only if the current profile cannot establish either the source or the target connection.
    • If the source or target protocol fragment defines protocol-specific alternatives (such as SFTPProtocolAlternatives), those alternatives are tried first.
      • The alternative_profile is considered only after all protocol-specific alternatives have been exhausted without successfully establishing a connection.
    • If an alternative profile defines its own alternative_profile, it is evaluated recursively.
    • To prevent circular references and duplicate processing, each referenced profile is evaluated at most once during the resolution process. If a profile has already been processed, it is skipped.
    • The profile that successfully establishes the connection is used for the subsequent file transfer.

Test Instructions

• Protocol Fragment Alternatives
  • Test with all supported providers and with Source and Target.
  • See the attached TEST-EXAMPLE-YADE-651.xml as an example.
    • The example configuration follows this concept:
      • Protocol fragments expected to fail are numbered (1, 2, 3, 4, ...), including the corresponding host names and user names, to make it easy to identify which alternative was used.
      • A protocol fragment named success is included and can establish the connection successfully.
  • Test different scenarios:
    • With and without a successful alternative.
    • Successful alternative at the beginning, middle, and end of the alternative chain.
    • With and without protocol fragment alternatives.
    • Nested protocol fragment alternatives.
    • With and without RetryOnConnectionErrors.
    • ...
    • Additionally, test with:
      • Jump host (both directions - jump an source/ jump on target).
      • SourceFileOptions / Polling.

• Profile alternative_profile
  • Test with and without protocol fragment alternatives.
  • Test with a jump host (both directions - jump an source/ jump on target).
  • Test: "The YADE CLI Client and YADE JITL Job support the alternative_profile argument"
    • Expected behaviour:
      • If the CLI or JITL job argument is set, it should either override the configured alternative_profile or set it if no alternative_profile is configured in the settings file.