From c7e68360fbede8ec417421f0333d0314cd9c4fea Mon Sep 17 00:00:00 2001 From: Timo Ley Date: Mon, 10 Apr 2023 16:10:08 +0200 Subject: [PATCH] env builder overhaul --- docs/SUMMARY.md | 6 ++-- docs/api/README.md | 2 +- docs/api/features/{env.md => builder.md} | 32 ++++++++++--------- docs/concepts/flags.md | 29 ++++++++--------- docs/concepts/instance.md | 6 ++-- ..._env_request.md => api_builder_request.md} | 0 ...nv_response.md => api_builder_response.md} | 2 +- docs/schema/manifest.md | 13 ++++++-- docs/schema/repository.md | 4 +-- 9 files changed, 50 insertions(+), 44 deletions(-) rename docs/api/features/{env.md => builder.md} (66%) rename docs/schema/{api_env_request.md => api_builder_request.md} (100%) rename docs/schema/{api_env_response.md => api_builder_response.md} (84%) diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 888596d..b4d1c63 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -7,7 +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) + - [Environment builder](api/features/builder.md) # Schema @@ -23,9 +23,9 @@ - [Library Object](schema/library.md) - [API Addon Object](schema/api_addon.md) - [API File Object](schema/api_file.md) -- [Environment Builder Request Object](schema/api_env_request.md) +- [Environment Builder Request Object](schema/api_builder_request.md) - [Addon Descriptor Object](schema/api_addon_descriptor.md) -- [Environment Builder Response Object](schema/api_env_response.md) +- [Environment Builder Response Object](schema/api_builder_response.md) # Concepts diff --git a/docs/api/README.md b/docs/api/README.md index 9064e88..a9f66c9 100755 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -66,4 +66,4 @@ These API features are part of the AddonScript specification itself: - `addons`: [Addon repository](./features/addons.md) - `files`: [File repository](./features/files.md) -- `env`: [Environment builder](./features/env.md) \ No newline at end of file +- `builder`: [Environment builder](./features/builder.md) \ No newline at end of file diff --git a/docs/api/features/env.md b/docs/api/features/builder.md similarity index 66% rename from docs/api/features/env.md rename to docs/api/features/builder.md index d475e3a..066cf0f 100644 --- a/docs/api/features/env.md +++ b/docs/api/features/builder.md @@ -8,44 +8,46 @@ 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 +If an [instance addon](../../concepts/instance.md), which has to provide a launch configuration, has +[`use_builder`](../../schema/manifest.md#usebuilder) set to `true`, AddonScript will send a request to this endpoint of an API instance, on which the [repository](../../schema/repository.md) of the [namespace](../../schema/manifest.md#namespace) of this addon can be found. -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. +This request contains information about the AddonScript [schema version](../../schema/api_builder_request.md#addonscript), +which will be used in the request and about which [addon](../../schema/api_builder_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) +[addon](../../schema/api_builder_request.md#addon) in this environment on that side. The [manifest](../../schema/manifest.md) +of this [addon](../../schema/api_builder_request.md#addon) uses the `expected` [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 later case, +[instance addon](../../concepts/instance.md), which inherits the launch configuration from this addon. In later 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 +to specify an exact version for each addon, that will be requested. Each required `expected` addon MUST be covered this way +while only those optional `expected` 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). +`expected` [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 +[file objects](../../schema/api_builder_response.md#files), the AddonScript +[schema version](../../schema/api_builder_response.md#addonscript) for the response and the +[launch configuration](../../schema/api_builder_response.md#launch) for this addon. 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. +and can then be installed. The launch configuration will override the +[local launch configuration](../../schema/manifest.md#launch) entirely. #### Request Body: -The request body MUST be an [Environment Builder Request Object](../../schema/api_env_request.md). +The request body MUST be an [Environment Builder Request Object](../../schema/api_builder_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). +The response body MUST be an [Environment Builder Response Object](../../schema/api_builder_response.md). - `400 Bad Request`: The server was not able to build the launch environment because of invalid information send by the client. The client SHOULD NOT try this request on another API instance, since the request is invalid. diff --git a/docs/concepts/flags.md b/docs/concepts/flags.md index 0a190d0..3b0c19e 100644 --- a/docs/concepts/flags.md +++ b/docs/concepts/flags.md @@ -16,10 +16,6 @@ addon manifest, including for which side it is available and for which side it i meaning, that this addon is not required on this side to be compatible, even if the other side has this addon installed. - `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. -- `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 get the launch files for this addon. - An addon with this flag MUST have a [repository](../schema/repository.md) for it's - [canonical namespace](../schema/manifest.md#namespace). ## Relational flags @@ -40,15 +36,16 @@ addon manifest, including for which side it is available and for which side it i [launch configuration](../schema/launch.md) should be inherited from the related addon (which MUST als be an instance addon or [Minecraft](./minecraft.md) itself). The inherited launch configuration, MAY still be modified using the [launch object](../schema/launch.md) of this addon. 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 +- `env` This flag is only valid for relations of [instance addons](instance.md). + An addon, that is inheriting the launch configuration from one, which uses the + [environment builder](../api/features/builder.md), uses this flag to tell AddonScript, which version of the `expected` + 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 `expected` addons will be part of the environment and which not. +- `expected` This flag is only valid for relations of [instance addons](instance.md), which use the + [environment builder](../api/features/builder.md). This flag speficies, that this addon expects the related addon + to be [requested](../schema/api_builder_request.md#requested) as a part of the + [launch environment](../api/features/builder.md#build-launch-environment). + 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. If an addon, which uses the + [environment builder](../api/features/builder.md), gets manually installed, meaning not as a dependency, the user + SHOULD be asked, which optional `expected` addons and which version of each `expected` addon will be requested. \ No newline at end of file diff --git a/docs/concepts/instance.md b/docs/concepts/instance.md index b040f19..9b83aa0 100644 --- a/docs/concepts/instance.md +++ b/docs/concepts/instance.md @@ -14,9 +14,9 @@ modifications to it. ## Instance addons as relations If an instance addon is a relation of another instance addon, each side of that -relation MUST have at least one of the [flags](flags.md) `included`, `launch`, `env` -or `incompatible`. Non-instance addons MAY have instance addons as relations without -this restriction. +relation MUST have at least one of the [flags](flags.md) `included`, `launch`, `env`, +`expect` or `incompatible`. Non-instance addons MAY have instance addons as relations +without this restriction. ## Launch configurations diff --git a/docs/schema/api_env_request.md b/docs/schema/api_builder_request.md similarity index 100% rename from docs/schema/api_env_request.md rename to docs/schema/api_builder_request.md diff --git a/docs/schema/api_env_response.md b/docs/schema/api_builder_response.md similarity index 84% rename from docs/schema/api_env_response.md rename to docs/schema/api_builder_response.md index 1e6356f..6a71e03 100644 --- a/docs/schema/api_env_response.md +++ b/docs/schema/api_builder_response.md @@ -13,7 +13,7 @@ ### 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). +It MUST be equal to the [addonscript Property](api_builder_request.md#addonscript) of the [request](api_builder_request.md). ### files diff --git a/docs/schema/manifest.md b/docs/schema/manifest.md index b02693a..84c7403 100644 --- a/docs/schema/manifest.md +++ b/docs/schema/manifest.md @@ -11,6 +11,7 @@ "flags": {}, "repositories": [], "instance": false, + "use_builder": false, "launch": {}, "meta": {} } @@ -54,15 +55,21 @@ 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. Each AddonScript manifest SHOULD have a repository for the [canonical namespace](#namespace) of -that manifest, from which AddonScript implementations MAY check for updates for this addon. If this addon has the `env` -[manifest flag](../concepts/flags.md#manifest-flags), it MUST have such a repository to provide API instances, which can -be used to request the [launch environment](../api/features/env.md#build-launch-environment). +that manifest, from which AddonScript implementations MAY check for updates for this addon. If [use_builder](#usebuilder) is `true`, +this addon MUST have such a repository to provide API instances, which can be used to request the +[launch environment](../api/features/builder.md#build-launch-environment). ### instance This is a boolean which specifies, if this addon is an [instance addon](../concepts/instance.md). If this property is not present, it defaults to `false`. +### use_builder + +This is a boolean which specifies, if this addon will use the [environment builder](../api/features/builder.md). +Only valid if [instance](#instance) is `true`. +If this property is not present, it defaults to `false`. + ### launch This is a [launch config object](launch.md) which can be used to modify the diff --git a/docs/schema/repository.md b/docs/schema/repository.md index 4111c80..f33080a 100644 --- a/docs/schema/repository.md +++ b/docs/schema/repository.md @@ -19,8 +19,8 @@ This is an array of base URLs of [AddonScript API](../api) instances, on which t repository can be found. To get an addon from this repository, AddonScript will try to get it from the [addon endpoint](../api/features/addons.md#get-addon) of these API instances in the order, in which they are specified in this array. -Instances in this array with the `env` [feature](../api/features/env.md) will +Instances in this array with the `builder` [feature](../api/features/builder.md) will be used by AddonScript, to request the launch environment for an addon with a [canonical namespace](../concepts/namespaces.md#canonical-namespaces) equal to the [namespace](#namespace) of this repository. The first API instance with -the `env` feature will be used in this case with the others as fallback. \ No newline at end of file +the `builder` feature will be used in this case with the others as fallback. \ No newline at end of file