davsclaus opened a new pull request, #3149:
URL: https://github.com/apache/camel-kamelets/pull/3149

   _Claude Code on behalf of Claus Ibsen_
   
   A batch of Kamelets rewritten to the documentation standard proposed in 
#3140, `docs/modules/ROOT/pages/documenting.adoc`, like #3141–#3148.
   
   This batch has 17 Kamelets and 14 partial pages:
   - `file-watch-source`;
   - the FTP, FTPS and SFTP sources and sinks, and `scp-sink`;
   - `ssh-source` and `ssh-sink`;
   - `mail-imap-source`, `mail-sink` and `ms-exchange-online-imap-oauth-source`;
   - `http-source`, `http-secured-source`, `http-secured-sink` and 
`rest-openapi-sink`.
   
   ## How they were checked
   
   **Every one was run against a local server:**
   - FTP, FTPS and SFTP from `camel infra`;
   - an OpenSSH container;
   - a GreenMail container for SMTP and IMAPS;
   - a local HTTP server and OpenAPI spec.
   
   The Exchange Kamelet was checked against its template and an equivalent IMAP 
route. It reaches Microsoft's login and fails there on a made-up tenant.
   
   ## Facts that were missing or wrong before
   
   - **`http-source` and `http-secured-source` do not listen: they poll a URL 
with a GET.**
     - `contentType` is the `Accept` header;
     - a status of 300 or more sends no message.
   - **The FTP, FTPS and SFTP sources:**
     - leave files on the server;
     - remember what they read only in memory, so after a restart they read 
everything again;
     - `ftps-*` support explicit TLS only, not implicit FTPS on port 990.
   - **The FTP, FTPS and SFTP sinks:** the file name comes from the `file` 
header, then `ce-file`, then `CamelFileName`, and otherwise a unique name is 
made.
   - **SFTP:**
     - checks the server's host key by default, so a new server needs 
`knownHostsUri` or an entry in `~/.ssh/known_hosts`;
     - `passiveMode` and `binary` do nothing for SFTP.
   - **`ssh-sink`:**
     - runs the body as a command, and says plainly that it runs whatever 
command it gets;
     - the output is stdout, plus the exit value and stderr as headers;
     - a non-zero exit does not fail the message.
   - **`mail-imap-source`:**
     - reads INBOX only, over IMAPS, and marks mail as read;
     - for a multipart mail the body is the first text part, not the 
attachments.
   - **`mail-sink`:**
     - the `ce-*` headers override the options;
     - `Content-Type: text/html` sends an HTML mail;
     - the default port is 465, not 25.
   - **`file-watch-source`:** the path must be a directory, and files already 
there at start are not sent.
   - **`rest-openapi-sink`:** path and query parameters come from headers of 
the same name.
   - **Partial pages:** most were corrected, for options that do not exist or 
wrong option names (`ssh-source`, `mail-imap-source`), features the Kamelets do 
not have (`sftp-sink`, `scp-sink`, `ssh-sink`), and a generic placeholder page 
(Exchange).
   
   ## Found on the way, not changed here
   
   - **`scp-sink`: two options make it fail to start** with `Unknown 
parameters`:
     - `knownHostsUri` (the scp option is `knownHostsFile`);
     - `privateKeyPassphrase` (the scp option is `privateKeyFilePassphrase`).
   
     These came in with #2967. Also, `scp-sink` has no directory option, so 
files always go to the user's home directory.
   - **`mail-sink`:** `from`, `to` and `subject` are not `required`, but the 
template uses them without `?`. Without one of them it fails to start.
   - **`rest-openapi-sink`:** `clientRequestValidation` is a consumer option, 
and has no effect in a sink. The producer option is `requestValidationEnabled`.
   - **`security-model.adoc` is wrong about `http-source` and 
`http-secured-source`:** it says they "open a platform-http listener", but they 
poll.
   - **Ports typed `string`:** `connectionPort` in the FTP, FTPS, SFTP, SSH and 
mail Kamelets.
   - **Commonly needed component options these Kamelets do not expose:**
     - file patterns, move after read, read locks and a persistent idempotent 
repository for the file sources;
     - a temporary name while uploading for the file sinks;
     - key login for SSH;
     - the folder and move/delete for IMAP;
     - cc/bcc and STARTTLS for mail;
     - a proxy and a bearer token for HTTP.
   
     These are for a follow-up.
   
   ## Notes for review
   
   - No template, type, default or required list was changed. The `dataTypes` 
blocks are `headers` only, with no `default`.
   - `KameletsCatalogTest.testSupportedHeaders`: the catalog now returns the 
headers these Kamelets declare instead of those of their components. The 
changed counts:
     - `file-watch-source` 10 → 3
     - `ftp-source`, `ftps-source`, `sftp-source` 15 → 4
     - `ftp-sink`, `ftps-sink`, `sftp-sink` 6 → 4
     - `http-source`, `http-secured-source` 5 → 2
     - `mail-sink` 8 → 6
     - `scp-sink` 0 → 1
     - `ssh-sink`, `ssh-source` 4 → 2
   - This PR is based on `main`; if #3140 merges first, I will rebase it and 
regenerate the index.
   
   `./mvnw clean install` from the root passes.
   
   🤖 Generated with [Claude Code](https://claude.com/claude-code)
   


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: [email protected]

For queries about this service, please contact Infrastructure at:
[email protected]

Reply via email to