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]