add documentation about user script

sunny-chung · Apr 17, 2024 · 38abbac · 38abbac
1 parent 5a226ae
commit 38abbac
Show file tree

Hide file tree

Showing 6 changed files with 220 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -90,6 +90,7 @@ Watch the images and videos on the [website](https://sunny-chung.github.io/hello
   - UUID (type `$((uuid))`)
   - Current date-time ISO-8601 string (type `$((now.iso8601))`)
   - Current timestamp (type `$((now.epochMills))` or `$((now.epochSeconds))`)
+- Executing custom safe script to mutate a Request before firing it
 - Copying as verbose cURL commands
 - Copying as verbose [grpcurl](https://github.com/fullstorydev/grpcurl) commands
 - Copying as PowerShell Invoke-WebRequest command (for Windows pwsh.exe)

diff --git a/doc/_include/pre-flight-script.png b/doc/_include/pre-flight-script.png
diff --git a/doc/_include/user-files.png b/doc/_include/user-files.png
diff --git a/doc/features/environments.md b/doc/features/environments.md
@@ -11,6 +11,7 @@ Each environment may contain the followings:
 - Zero or more variables
 - HTTP protocol version preference
 - SSL verification preference
+- Zero or more user files (for scripts)
 
 ## Creating an Environment
 

diff --git a/doc/features/user-script.md b/doc/features/user-script.md
@@ -0,0 +1,217 @@
+---
+title: User Script
+---
+
+# User Script
+
+Hello HTTP allows the use of custom script to perform a limited set of operations that are not possible or difficult to do via the UI. The supported programming language is [Kotlite](https://sunny-chung.github.io/kotlite/#_the_kotlite_language), a subset of the **Common** variant of the [Kotlin](https://kotlinlang.org/docs/basic-syntax.html) 1.9 **script** language. Script means it does not require a `main` function and the statements at the outermost scope will be executed sequentially.
+
+It is not quite possible to do anything harmful by user scripts, because both the language and the APIs available to be used are limited. For example, it is not possible to make another HTTP request directly from the script, nor modify the URL of the current script, nor execute system commands.
+
+An example use case of user script is to generate some hash or signature with some encryption keys and embed into a request before sending it.
+
+## Providing custom files for user script use
+
+Files can be imported into an [Environment](environments) to be used by user script. Only small files can be imported.
+
+![User Files](../user-files.png)
+
+Names can be changed after importing.
+
+## Pre-flight Script
+
+Custom pre-flight script can be provided to a [request example](request-examples-and-payload-examples). It would be executed before firing the request.
+
+It is only available for:
+- Plain/RESTful HTTP requests
+- GraphQL requests
+
+Similar to other request example properties, the script in the "Base" example can be overridden by other request examples.
+
+![Pre-flight Script](../pre-flight-script.png)
+
+The only supported mutation operations are:
+- append headers
+- append query parameters
+
+All APIs in the [standard library](https://sunny-chung.github.io/kotlite/#_built_in_and_standard_library_apis) can be used.
+
+In additional, below inputs and APIs are available as follow.
+
+### Global Properties
+
+```kotlin
+/**
+ * Request object.
+ * 
+ * @param <BODY> One of `Nothing`, `StringBodyClass`, `FormUrlEncodedBodyClass`, `MultipartBodyClass`, `FileBodyClass`, `GraphqlBodyClass`.
+ */
+val request: MutableRequest<BODY>
+
+/**
+ * The environment chosen to be active. Null if there is none.
+ */
+val environment: Environment?
+```
+
+### Types
+
+#### `Request`
+
+```kotlin
+class Request<BODY>
+
+val Request<*>.url: String
+val Request<*>.method: String
+val Request<*>.headers: List<Pair<String, String>>
+val Request<*>.queryParameters: List<Pair<String, String>>
+val <BODY> Request<BODY>.body: BODY?
+
+/**
+ * Get a properly encoded URI embedded with query parameters.
+ */
+fun Request<*>.getResolvedUri(): String
+```
+
+#### `MutableRequest`
+
+```kotlin
+class MutableRequest<BODY> : Request<BODY>
+
+fun MutableRequest<*>.addHeader(key: String, value: String)
+fun MutableRequest<*>.addQueryParameter(key: String, value: String)
+```
+
+#### `Environment`
+
+```kotlin
+class Environment
+
+val Environment.name: String
+
+/**
+ * Environment variables. Only enabled variables are available.
+ */
+val Environment.variables: List<UserKeyValuePair>
+
+/**
+ * User files. Only enabled user files are available.
+ */
+val Environment.userFiles: List<ImportedFile>
+```
+
+#### `UserKeyValuePair`
+
+```kotlin
+class UserKeyValuePair
+
+val UserKeyValuePair.key: String
+val UserKeyValuePair.value: String
+
+/**
+ * Either "String" or "File".
+ */
+val UserKeyValuePair.valueType: String
+
+/**
+ * If valueType is "String", return the bytes of the String value.
+ * If valueType is "File", return the bytes of the underlying file, or null if no file is selected. Exception would be thrown if a file is specified and cannot be read.
+ */
+fun UserKeyValuePair.readValueBytes(): ByteArray?
+```
+
+#### `StringBody`
+
+```kotlin
+class StringBody
+
+val StringBody.value: String
+```
+
+#### `FormUrlEncodedBody`
+
+```kotlin
+class FormUrlEncodedBody
+
+val FormUrlEncodedBody.value: List<UserKeyValuePair>
+```
+
+#### `MultipartBody`
+
+```kotlin
+class MultipartBody
+
+val MultipartBody.value: List<UserKeyValuePair>
+```
+
+#### `FileBody`
+
+```kotlin
+class FileBody
+
+val FileBody.filePath: String?
+
+/**
+ * Return the bytes of the underlying file, or null if no file is selected. Exception would be thrown if a file is specified and cannot be read.
+ */
+val FileBody.readBytes(): ByteArray?
+```
+
+#### `GraphqlBody`
+
+```kotlin
+class GraphqlBody
+
+val GraphqlBody.document: String
+val GraphqlBody.variables: String
+val GraphqlBody.operationName: String?
+```
+
+#### `ImportedFile`
+
+```kotlin
+class ImportedFile
+
+val ImportedFile.name: String
+val ImportedFile.originalFilename: String
+val ImportedFile.createdWhen: KInstant
+val ImportedFile.content: ByteArray
+```
+
+#### `PublicKey`
+
+```kotlin
+class PublicKey
+```
+
+#### `PrivateKey`
+
+```kotlin
+class PrivateKey
+```
+
+### Extensions
+
+#### Encoding
+
+````kotlin
+fun ByteArray.encodeToBase64String(): String
+fun ByteArray.encodeToBase64UrlString(): String
+fun ByteArray.encodeToHexString(): String
+
+fun String.decodeJsonStringToMap(): Map<Any?, Any?>
+````
+
+#### Crypto
+
+````kotlin
+fun ByteArray.toSha1Hash(): ByteArray
+fun ByteArray.toSha256Hash(): ByteArray
+fun ByteArray.toSha512Hash(): ByteArray
+fun ByteArray.toMd5Hash(): ByteArray
+fun ByteArray.toSha1WithRsaSignature(rsaPrivateKey: PrivateKey): ByteArray
+fun ByteArray.toSha256WithRsaSignature(rsaPrivateKey: PrivateKey): ByteArray
+
+fun ByteArray.toPkcs8RsaPublicKey(): PublicKey
+fun ByteArray.toPkcs8RsaPrivateKey(): PrivateKey
+````
diff --git a/doctave.yaml b/doctave.yaml
@@ -14,6 +14,7 @@ navigation:
       - path: doc/features/environments.md
       - path: doc/features/ssl-configuration.md
       - path: doc/features/functions.md
+      - path: doc/features/user-script.md
       - path: doc/features/post-flight-actions.md
       - path: doc/features/viewing-responses.md
       - path: doc/features/transport-timeline.md