(new): expand runtime APIs

(fix): harden concurrent lifecycle
(tests): add regression coverage
(doc): update v1.2 guidance

bot_opts.go

@@ -54,8 +54,8 @@ type BotOpts struct {
 	// Telegram allows up to 30 req/s for most bots. Defaults to 30.
 	RateLimit int
 
-	// DropRateLimitOverflow drops incoming updates when rate limit is exceeded instead of queuing.
-	// Use this to prioritize responsiveness over reliability.
+	// DropRateLimitOverflow rejects outgoing Telegram API requests immediately when
+	// rate-limit capacity is unavailable instead of waiting for capacity.
 	DropRateLimitOverflow bool
 
 	// StrictPayloadType disables callback payload fallback decoding.
@@ -96,7 +96,7 @@ type BotOpts struct {
 //   - USE_TEST_SERVER: "true" to use Telegram test server
 //   - API_URL: custom API endpoint
 //   - RATE_LIMIT: max requests per second (default: 30)
-//   - DROP_RL_OVERFLOW: "true" to drop updates on rate limit overflow
+//   - DROP_RL_OVERFLOW: "true" to reject rate-limited API requests instead of waiting
 //   - STRICT_PAYLOAD_TYPE: "true" to reject callback payloads encoded in a different format
 //   - MAX_WORKERS: maximum number of concurrent update handlers (default: 32)
 //   - POLL_TIMEOUT: long-polling timeout in seconds for getUpdates (default: 30)
@@ -237,8 +237,8 @@ func (opts *BotOpts) SetRateLimit(limit int) *BotOpts {
 	return opts
 }
 
-// SetDropRateLimitOverflow drops incoming updates when rate limit is exceeded instead of queuing.
-// Use this to prioritize responsiveness over reliability. Default is false.
+// SetDropRateLimitOverflow configures outgoing Telegram API requests to fail
+// immediately when rate-limit capacity is unavailable. Default is false.
 func (opts *BotOpts) SetDropRateLimitOverflow(drop bool) *BotOpts {
 	opts.DropRateLimitOverflow = drop
 	return opts