docs: rule and stream update (#3896)

Signed-off-by: Jiyong Huang <huangjy@emqx.io>

Author: ngjaying

docs/en_US/api/restapi/rules.md

@@ -100,9 +100,10 @@ Example response when using slice mode:
 }
 ```
 
-## update a rule
+## upsert a rule
 
-The API accepts a JSON content and update a rule.
+The API accepts a JSON content and upsert a rule which means if the rule is not existed, create it; otherwise, update
+it. If update fails, the original rule will continue running.
 
 ```shell
 PUT http://localhost:9081/rules/{id}
@@ -132,15 +133,19 @@ DELETE http://localhost:9081/rules/{id}
 
 ## start a rule
 
-The API is used to start running the rule.
+The API is used to start running the rule. Please note that the command only indicates the successful transmission of
+the start instruction. To verify if the rule has completed startup, the rule status must be checked. If the rule is
+currently in the process of starting or stopping, the start instruction will be added to the rule's command queue.
 
 ```shell
 POST http://localhost:9081/rules/{id}/start
 ```
 
 ## stop a rule
 
-The API is used to stop running the rule.
+The API is used to stop running the rule. Please note that the command only indicates the successful transmission of the
+stop instruction. To verify if the rule has completed startup, the rule status must be checked. If the rule is currently
+in the process of starting or stopping, the start instruction will be added to the rule's command queue.
 
 ```shell
 POST http://localhost:9081/rules/{id}/stop

docs/en_US/api/restapi/schemas.md

@@ -117,23 +117,8 @@ PUT http://localhost:9081/schemas/protobuf/{name}
 The schema can have an optional **version** field. This field is essential for controlling updates and ensuring that new
 schemas are correctly applied. When you update a schema, the system compares the new version string to the existing one.
 An update is only accepted if the new version is **lexically greater** than the old one. This comparison is a
-character-by-character string comparison, not a numerical one.
-
-### Versioning Logic
-
-- **No Version Specified:** If neither the old nor the new schema has a `version` field, the update will proceed. This
-  behavior aligns with the original, unversioned logic.
-- **Versioning Set:** If a `version` field is present in either the old or the new schema, the system will always
-  perform a version comparison. The presence of any version string triggers the new comparison logic.
-- **Lexical Comparison:** Updates are based on a lexical (string) comparison. The new schema's `version` must be
-  lexicographically greater than the current one for the update to be successful.
-- **Smallest Version:** A schema without a `version` field is considered to have the "smallest possible" version. This
-  means that adding a version field to an existing, unversioned schema will always result in a successful update, as any
-  new version string will be lexically greater than the non-existent one.
-
-To avoid confusion and ensure correct ordering, it's highly recommended to use a **timestamp** as the version string.
-Timestamps, such as Unix epoch time, provide a universally unique and monotonically increasing value that naturally
-satisfies the lexical comparison rule.
+character-by-character string comparison, not a numerical one. The control logic for all versioned APIs is the same;
+please refer to the [Versioning Logic](../../guide/rules/overview.md#versioning-logic) for details.
 
 Below is an example schema request with version:
 

docs/en_US/concepts/rules.md

@@ -4,16 +4,54 @@ Each rule represents a computing job to run in eKuiper. It defines the continuou
 
 ## Rule Lifecycle
 
-Currently, eKuiper only supports stream processing rule, which means that at lease one of the rule source must be a continuous stream. Thus, the rule will run continuously once started and only stopped if the user send stop command explicitly. The rule may stop abnormally for errors or the eKuiper instance exits.
+eKuiper currently **only supports Streaming Rules**. These types of rules require at least one Continuous Stream as a
+data source.
+
+Once a rule is started, it will run continuously until:
+
+1. The user explicitly sends a stop command.
+2. The rule abnormally terminates due to an internal error or the eKuiper instance exiting.
+
+**Asynchronous Rule Startup and Status Management**
+
+The rule startup process is **asynchronous**. When a user sends a start command, eKuiper performs necessary static
+checks and then asynchronously executes the rule's startup operation. Therefore:
+
+* The command response received by the user only indicates that eKuiper has accepted the startup request and set the
+  rule's **Expected Status** to 'started'.
+* This does not mean the rule has begun running. Users need to further check the rule's **Runtime Status** to confirm
+  that the rule has successfully started and is running.
+
+**Rule Update and Error Rollback**
+
+During the rule update process, eKuiper provides **rollback** support. If the updated rule fails to start, the system
+will automatically maintain and continue running the original old rule to ensure service stability.
 
 ## Rules Relationship
 
 It is common to run multiple rules simultaneously. As eKuiper is a single instance process, the rules are running in the same memory space. However, there are separated in the runtime and the error in one rule should not affect others. Regarding workload, all rules share the same hardware resource. Each rule can specify the operator buffer to limit the processing rate to avoid taking all resources.
 
+When multiple rules use a **[Shared Stream](../guide/streams/overview.md#share-source-instance-across-rules)**, they
+share the upstream source components, including data ingestion and decoding.
+
+In execution, all rules utilizing a shared stream form a single **Directed Acyclic Graph (DAG)** where downstream rules
+can be dynamically added or removed.
+
+**Impact of Shared Streams**
+
+Due to this shared structure, rules within the DAG will influence each other. Specifically:
+
+* **Backpressure Propagation:** Backpressure originating from one rule can propagate backward through the shared source
+  component.
+* **Wider Impact:** This backpressure on the shared stream will then affect the performance and processing of **all**
+  other rules connected to that same shared source.
+
+Besides this, the shared source side ignores checkpoint.
+
 ## Rule Pipeline
 
 Multiple rules can form a processing pipeline by specifying a joint point in sink/source. For example, the first rule produce the result to a topic in memory sink and the other rule subscribe to that topic in its memory source. Besides the pair of memory sink/source, users can also use mqtt or other sink/source pair to connect rules.
 
 ## More Readings
 
-- [Rule Reference](../guide/rules/overview.md)
+* [Rule Reference](../guide/rules/overview.md)

docs/en_US/configuration/global_configurations.md

@@ -46,6 +46,8 @@ basic:
   rulePatrolInterval: 10s
   # cfgStorageType indicates the storage type to store the config, support `file` and `kv`. When `cfgStorageType` is file, it will save configuration into File. When `cfgStorageType` is `kv`, it will save configuration into the storage defined in `store`
   cfgStorageType: file
+  # If it is enabled, each REST API call will print logs
+  enableRestAuditLog: false
 ```
 
 for debug option in basic following env is valid `KUIPER__BASIC__DEBUG=true` and if used debug value will be set to true.
@@ -340,7 +342,9 @@ This section configures the portable plugin runtime.
 
 ## Ruleset Provision
 
-Support file based stream and rule provisioning on startup. Users can put a [ruleset](../api/restapi/ruleset.md#ruleset-format) file named `init.json` into `data` directory to initialize the ruleset. The ruleset will only be import on the first startup of eKuiper.
+Support file based stream and rule provisioning on startup. Users can put
+a [ruleset](../api/restapi/ruleset.md#ruleset-format) file named `init.json` into `etc` directory to initialize the
+ruleset. The ruleset will only be import on the first startup of eKuiper.
 
 ## Configure FoundationDB as storage