diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 860f877..3d0dfcc 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -7,6 +7,7 @@ - [AddonScript API](api/README.md) - [Addon repository](api/features/addons.md) - [File repository](api/features/files.md) + - [Environment builder](api/features/env.md) # Schema @@ -18,8 +19,11 @@ - [Flags Object](schema/flags.md) - [Repository Object](schema/repository.md) - [Meta Object](schema/meta.md) -- [API Addon](schema/api_addon.md) -- [API File](schema/api_file.md) +- [API Addon Object](schema/api_addon.md) +- [API File Object](schema/api_file.md) +- [Environment Builder Request Object](schema/api_env_request.md) + - [Addon Descriptor Object](schema/api_addon_descriptor.md) +- [Environment Builder Response Object](schema/api_env_response.md) # Concepts diff --git a/docs/api/README.md b/docs/api/README.md index 8249d96..6a3284d 100755 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -36,4 +36,5 @@ be in a namespace-like format (reversed domain name). These API features are part of the AddonScript specification itself: - `addons`: [Addon repository](./features/addons.md) -- `files`: [File repository](./features/files.md) \ No newline at end of file +- `files`: [File repository](./features/files.md) +- `env`: [Environment builder](./features/env.md) \ No newline at end of file diff --git a/docs/api/features/env.md b/docs/api/features/env.md new file mode 100644 index 0000000..6d224cc --- /dev/null +++ b/docs/api/features/env.md @@ -0,0 +1,51 @@ +# Environment builder + +## Endpoints + +### Build launch environment + +`POST {base URL}/v2/env` + +This endpoint can be used to build the launch environment for an [instance addon](../../concepts/instance.md). + +If an [instance addon](../../concepts/instance.md), which has to provide a launch configuration, has the +`env` [manifest flag](../../concepts/flags.md#manifest-flags), AddonScript will send a request to this +endpoint if the API instance [specified in the manifest](../../schema/manifest.md#envapi) of that addon. +This request contains information about the AddonScript [schema version](../../schema/api_env_request.md#addonscript), +which will be used in the request and about which [addon](../../schema/api_env_request.md#addon) this request is for. +Moreover it contains for both sides a list of addons, including their version, which will be part of the +[addon](../../schema/api_env_request.md#addon) in this environment on that side. The [manifest](../../schema/manifest.md) +of this [addon](../../schema/api_env_request.md#addon) uses the `env` [relation flag](../../concepts/flags.md#relational-flags) +to tell AddonScript, which [related addons](../../schema/relation.md) MAY and which MUST be requested on this endpoint +and which [versions](../../schema/relation.md#version) of them are valid. Which exact version of them and which optional +addons will be requested is either decided by the user, if the instance addon is installed manually, or by another +[instance addon](../../concepts/instance.md), which delegates the launch configuration to this addon. In latetr case, +that [instance addon](../../concepts/instance.md) uses the `env` [relation flag](../../concepts/flags.md#relational-flags) +to specify an exact version for each addon, that will be requested. Each required `env` addon MUST be covered this way +while only those optional `env` addons will be requested, which are covered this way. Lastly the request also contains +for each side a list of all [related addons](../../schema/relation.md) of this one, which are or will be installed +into this instance, including their version. This does not include [relations](../../schema/relation.md) with the +`env` [relation flag](../../concepts/flags.md#relational-flags). + +Since the API instance MAY download files or build/compile things to build the launch environment, this request MAY +take some time so the client implementation SHOULD set the request timeout for this endpoint rather high. It is +RECOMMENDED to have a timeout of at least 5 minutes, better about 10 minutes. + +After the launch environment was build by the API instance, this endpoint will respond with a list of +[file objects](../../schema/api_env_response.md#files) and the AddonScript +[schema version](../../schema/api_env_response.md#addonscript) for the response. These files MUST be considered +to be part of the [files](../../schema/manifest.md#files) of the addon, from which the request was send +and can then be installed. + +#### Request Body: + +The request body MUST be an [Environment Builder Request Object](../../schema/api_env_request.md). + +#### Responses: + +- `200 OK`: The launch environment was successfully build. +The response body MUST be an [Environment Builder Response Object](../../schema/api_env_response.md). +- `400 Bad Request`: The server was not able to build the launch environment because of +invalid information sned by the client. +- `500 Internal Server Error`: The server was not able to build the launch environment +because of an internal error. \ No newline at end of file diff --git a/docs/concepts/flags.md b/docs/concepts/flags.md index 51a6813..ecfa6a4 100644 --- a/docs/concepts/flags.md +++ b/docs/concepts/flags.md @@ -17,6 +17,9 @@ addon manifest, including for which side it is available and for which side it i - `incompatible` This flag specifies, that the manifest is not compatible with the side which has this flag set. If a side has this flag, this side will completly be ignored for the manifest. - `instance` This flag specifies, that this is a manifest of an [instance addon](instance.md). +- `env` This flag is only valid for [instance addons](instance.md). It specifies, that the + [environment builder API](../api/features/env.md) will be used to bet the launch files for this addon. + An addon with this flag MUST have the [env_api](../schema/manifest.md#envapi) property. ## Relational flags @@ -33,10 +36,22 @@ addon manifest, including for which side it is available and for which side it i - `incompatible` This flag specifies for a relation, that the related addon is incompatible to this one, which means, that they can't be installed together in the same instance. For a file this flag specifies, that the file can't be installed on the side which has this flag set. -- `launch` This flag is only valid for instance addons. For a relation this flag specifies, that the launch configuration - will be delegated to the related addon. The related addon MUST also be an instance addon on that side. For a file this - flag specifies, that the file will be the launch file of this addon. On the client side the launch file MUST be a - [client JSON file](https://minecraft.fandom.com/wiki/Client.json) which contains the client launch configuration. - On the server side the launch file MUST be an executable jar file, which will be executed to start the server. - This jar file will implicitly be installed by being moved to the root of the server directory. This flag always - also implies any effect of `required`. \ No newline at end of file +- `launch` This flag is only valid for [instance addons](instance.md). For a relation this flag specifies, that the launch + configuration will be delegated to the related addon. The related addon MUST also be an instance addon on that side. + For a file this flag specifies, that the file will be the launch file of this addon. On the client side the launch + file MUST be a [client JSON file](https://minecraft.fandom.com/wiki/Client.json) which contains the client launch + configuration. On the server side the launch file MUST be an executable jar file, which will be executed to start + the server. This jar file will implicitly be installed by being moved to the root of the server directory. + This flag always also implies any effect of `required`. +- `env` This flag is only valid for relations of [instance addons](instance.md). It MUST only be used for instance + addons, that either have the `env` [manifest flag](#manifest-flags) or are delegating the launch configuration + to such an addon. This flag speficies, that the related addon will be [requested](../schema/api_env_request.md#requested) + to be part of the [launch environment](../api/features/env.md#build-launch-environment). For the addon, for + which the launch environment will be build, it is used together with the `required` or `optional` flag + to specify, which addons are required for the launch environment, which are optional and which versions + of them are valid. An addon, that is delegating the launch configuration to one, which has the `env` + [manifest flag](#manifest-flags), uses this flag to tell AddonScript, which version of the addons will be requested + for the environment by setting an exact [version](../schema/relation.md#version) for the relation. It also tells + AddonScript, which optional `env` addons will be part of the environment. If an addon with the `env` + [manifest flag](#manifest-flags) gets manually installed, meaning not as a dependency, the user SHOULD be asked, + which optional `env` addons and which version of each `env` addon will be requested. \ No newline at end of file diff --git a/docs/schema/api_addon_descriptor.md b/docs/schema/api_addon_descriptor.md new file mode 100644 index 0000000..85e3cd4 --- /dev/null +++ b/docs/schema/api_addon_descriptor.md @@ -0,0 +1,24 @@ +# Addon Descriptor Object + +```json +{ + "id": "addonid", + "namespace": "com.example", + "version": "1.0.0" +} +``` + +## Required properties + +### id + +This is the [ID](manifest.md#id) of the addon which this object describes. + +### namespace + +This is the [namespace](../concepts/namespaces.md) of the addon which this object describes. +It SHOULD be the [canonical namespace](../concepts/namespaces.md#canonical-namespaces). + +### version + +This is the [version](manifest.md#version) of the addon. \ No newline at end of file diff --git a/docs/schema/api_env_request.md b/docs/schema/api_env_request.md new file mode 100644 index 0000000..ca224f6 --- /dev/null +++ b/docs/schema/api_env_request.md @@ -0,0 +1,56 @@ +# Environment Builder Request Object + +```json +{ + "addonscript": {}, + "addon": {}, + "client": {}, + "server": {} +} +``` + +## Required properties + +### addonscript + +This is an [AddonScript object](addonscript.md) containing information about the version of AddonScript used in this request. +It SHOULD be equal to the [addonscript Property](manifest.md#addonscript) of the [manifest](manifest.md) from which the request +was send. + +### addon + +This is an [addon descriptor object](api_addon_descriptor.md), which contains the [addon ID](manifest.md#id), +[canonical namespace](manifest.md#namespace) and [version](manifest.md#version) of the addon, for which the +launch environment will be build. + +## Optional properties + +### client + +This is an [environment object](#environment-object) containing information about the client environment. + +### server + +This is an [environment object](#environment-object) containing information about the server environment. + +# Environment Object + +```json +{ + "requested": [], + "provided": [] +} +``` + +## Optional properties + +### requested + +This is an array of [addon descriptor objects](api_addon_descriptor.md) which contains all addons, that will +be part of the launch environment, including their version. + +### provided + +This is an array of [addon descriptor objects](api_addon_descriptor.md) which contains all addons from the +[relations](manifest.md#relations) of the [addon](#addon), from which the request was send, that will be installed +in the instance, including their version \ No newline at end of file diff --git a/docs/schema/api_env_response.md b/docs/schema/api_env_response.md new file mode 100644 index 0000000..4a41693 --- /dev/null +++ b/docs/schema/api_env_response.md @@ -0,0 +1,20 @@ +# Environment Builder Response Object + +```json +{ + "addonscript": {}, + "files": [] +} +``` + +## Required properties + +### addonscript + +This is an [AddonScript object](addonscript.md) containing information about the version of AddonScript used in this response. +It MUST be equal to the [addonscript Property](api_env_request.md#addonscript) of the [request](api_env_request.md). + +### files + +This is an array of [File objects](file.md). These files will be concidered to be files of the addon, for which the launch +environment was build, and MUST be treated equal to the [files in the manifest](manifest.md#files). \ No newline at end of file diff --git a/docs/schema/manifest.md b/docs/schema/manifest.md index a42593b..8cad994 100644 --- a/docs/schema/manifest.md +++ b/docs/schema/manifest.md @@ -11,6 +11,7 @@ "relations": [], "flags": {}, "repositories": [], + "env_api": "https://example.com", "meta": {} } ``` @@ -60,6 +61,12 @@ This is an array of [relation objects](relation.md) which represent addons in re This is an array of [repository objects](repository.md). Each repository object defines one repository from which files or addons can be retrieved. +### env_api + +This is the base URL of an [AddonScript API](../api) instance, which has the `env` feature and will be used to +build the launch environment for this addon. This property will only be used if this addon has the `env` +[manifest flag](../concepts/flags.md#manifest-flags). + ### meta This is a [meta object](meta.md) containing metadata about the addon.