update readmes

WebHooks/README.md

@@ -1,28 +1,52 @@
 # WebHooks
 
-Launches webhook-based simple bot. Use `/start` with bot to get simple info about webhooks
+A webhook-based example bot with an embedded Ktor CIO server. It registers a public webhook URL with Telegram, accepts update POSTs on a matching local route, and dispatches them through a behavior context; it does not use long polling.
+
+## Server and bot behavior
+
+- The server binds plain HTTP to `0.0.0.0` on the selected port (`8080` by default) and blocks until it is stopped.
+- With no subpath, webhook POSTs are handled at `/`. With a subpath such as `telegram/hooks`, they are handled at `/telegram/hooks`, and that path is appended to the registered public address.
+- An accepted update POST receives HTTP `200`; malformed JSON or a synchronous dispatch failure receives HTTP `500`. Later handler exceptions are printed by the behavior context. No health-check or other application route is installed.
+- The bot registers all supported update types. Pending updates are not explicitly dropped when the webhook is set, and the webhook remains registered after this process exits.
+- `/start` works only in a private chat and replies with the configured external address, local bind host (`0.0.0.0`), and port. The displayed address does not include the optional subpath. The command is ignored in groups.
+
+The example does not configure a webhook `secret_token` and does not validate Telegram's secret-token header. Anyone who can reach the endpoint can submit update-shaped JSON, so protect the endpoint at the network/proxy layer or add secret-token verification before production use.
+
+## TLS, certificates, and networking
+
+The embedded server has no HTTPS connector and loads no certificate. The `setWebhook` call also uploads no public certificate. In a typical deployment:
+
+1. Point a public DNS name at a reverse proxy or load balancer reachable from Telegram.
+2. Terminate HTTPS there with a publicly trusted certificate.
+3. Forward the webhook path to this process over HTTP on its internal port.
+4. Allow Telegram to reach the public listener through any firewall/NAT rules. Telegram webhook listeners use public ports `443`, `80`, `88`, or `8443`; the internal forwarded port can remain `8080`.
+
+Self-signed-certificate deployment is not supported by this example as written because it neither serves TLS nor passes a certificate to `setWebhook`. The external address must start with `https://`; avoid a trailing slash when also supplying a subpath, otherwise the registered URL contains a doubled slash.
+
+## Arguments and environment
+
+Create a bot with [@BotFather](https://t.me/BotFather) and obtain its token. All runtime configuration then comes from positional command-line arguments; no environment variables are read.
+
+- The first argument is the required bot token.
+- The first argument beginning with `https://` is the required public address.
+- `debug` anywhere enables formatted default KSLog output.
+- The first integer-valued argument becomes the local port; otherwise it is `8080`.
+- The first argument after the token that is neither the chosen address nor exactly `debug` becomes the optional subpath. A leading `/` is normalized for the public URL.
+
+The parser also treats a numeric port argument as a subpath candidate. Therefore `TOKEN ADDRESS 9000` registers `/9000` and listens on port `9000`; the current CLI cannot select a custom port while keeping the webhook route at `/`. Put a nonnumeric subpath before the port when both are wanted. Additional arguments are otherwise ignored.
 
 ## Launch
 
+From the repository root, the minimal form uses `/` and port `8080`:
+
 ```bash
-../gradlew run --args="BOT_TOKEN https://sample.com it/is/subpath 8080 debug"
+./gradlew :WebHooks:run --args="<BOT_TOKEN> https://bot.example.com"
 ```
 
-Required arguments:
+Example with a subpath, custom internal port, and debug logging:
 
-1. Token
-2. Arguments starting with `https://`
+```bash
+./gradlew :WebHooks:run --args="<BOT_TOKEN> https://bot.example.com telegram/hooks 9000 debug"
+```
 
-Optional arguments:
-
-* Any argument == `debug` to enable debug mode
-* Any argument **not** starting with `https://` and **not** equal to `debug` as **subpath** (will be used as
-subroute to place listening of webhooks)
-* Any argument as number of port
-
-Sample: `TOKEN https://sample.com it/is/subpath 8080` will result to:
-
-* `TOKEN` used as token
-* Bot will set up its webhook info as `https://sample.com/it/is/subpath`
-* Bot will set up to listen webhooks on route `it/is/subpath`
-* Bot will start to listen any incoming request on port `8080` and url `0.0.0.0`
+That command registers `https://bot.example.com/telegram/hooks` and binds the forwarded POST route as `/telegram/hooks` on local port `9000` across all network interfaces.

WebHooks/src/main/kotlin/WebHooks.kt

@@ -16,24 +16,16 @@ import dev.inmo.tgbotapi.utils.buildEntities
 import io.ktor.server.routing.*
 
 /**
- * Launches webhook-based simple bot. Required arguments:
+ * Registers a Telegram webhook and starts a blocking, plain-HTTP Ktor server for its update POSTs.
  *
- * 1. Token
- * *. Arguments starting with `https://`
+ * The first argument is the bot token and the first `https://` argument is the public webhook address. The first
+ * remaining non-`debug` argument becomes the optional route, the first integer becomes the port (default `8080`),
+ * and an argument exactly equal to `debug` enables formatted KSLog output. A numeric port can also be selected as the
+ * route because route parsing is performed independently.
  *
- * Optional arguments:
+ * TLS termination and certificate provisioning must be handled outside this process.
  *
- * *. Any argument == `debug` to enable debug mode
- * *. Any argument **not** starting with `https://` and **not** equal to `debug` as **subpath** (will be used as
- * subroute to place listening of webhooks)
- * *. Any argument as number of port
- *
- * Sample: `TOKEN https://sample.com it/is/subpath 8080` will result to:
- *
- * * `TOKEN` used as token
- * * Bot will set up its webhook info as `https://sample.com/it/is/subpath`
- * * Bot will set up to listen webhooks on route `it/is/subpath`
- * * Bot will start to listen any incoming request on port `8080` and url `0.0.0.0`
+ * @param args positional webhook/server configuration described above
  */
 suspend fun main(args: Array<String>) {
     val botToken = args.first()