Merge pull request 'Environment builder spec' (#25) from tilera/addonscript-spec:master into master

Reviewed-on: addonscript/addonscript-spec#25

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
 

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)
+- `files`: [File repository](./features/files.md)
+- `env`: [Environment builder](./features/env.md)

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.

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`.
+- `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.

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.

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

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).

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.