env builder overhaul

This commit is contained in:
Timo Ley 2023-04-10 16:10:08 +02:00
parent 41fe553787
commit c7e68360fb
9 changed files with 50 additions and 44 deletions

View file

@ -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

View file

@ -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)
- `builder`: [Environment builder](./features/builder.md)

View file

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

View file

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

View file

@ -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

View file

@ -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

View file

@ -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

View file

@ -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.
the `builder` feature will be used in this case with the others as fallback.