# Extensions Proposal This is a design document proposing the Blender extensions platform. Online Extensions ================= The online-extensions platform is a separate project, however it is expected that the Blender integration will be able to use online repositories to list and install extensions. This proposal works under the assumption that ``blender.org`` will maintain a list of add-ons, where the majority of add-ons currently included with Blender will be moved to. These add-ons will be maintained by their respective authors, instead of having to maintain them centrally. Communities are free to setup their own lists of add-ons although Blender will only enable the official ``blender.org`` repository by default. Including other repositories will be supported with minimal hassle with the understanding users are trusting the judgment of the people who setup such lists. Initial Proposal ================ Requirements ------------ - Support for multiple extension repositories (repos). Studios and individual users should be able to host their own extensions. - Support both online repos as well as local (file-system) based repositories, useful for developers, studios as well as running automated tests. - Support for multiple extension types (add-ons, apps, themes). - Building and updating extensions must be automated, where a change to an extension can be published without tedious web-UI's. - Support being disabled entirely. There is no requirement that external extensions must be used. It should be possible to opt-out of using extensions. *As long as automated updates are off by default, there is no need to use extensions unless users explicitly do so.* Non-Goals --------- - Support for large multi-gigabyte extensions. Very large repositories (typically used for assets) are outside the scope of this project. Extensions may be re-downloading during an update for example. - Providing rich text and setting ratings etc from within Blender's UI. - Automatic updates (initially), while this can be supported the initial version will require manual updates. Components ---------- - extension-builder A tool that validates metadata and packages the extension into an archive (perhaps an archive and generated metadata). Also used for generating a repository listing (which would be downloaded by the client to show before extensions before they're). - extension-publish (not part of MVP) Handles uploading the extension, authentication. May also do sanity checks - such as versions never decreasing. - extension-validate Used by the builder and server to validate extensions. - extension-client This utility would be responsible for adding/removing extensions, listing extensions from a repository. This is responsible for gracefully handling errors & cleaning up in the event of failure (network-error, disk-full ... etc). - blender-integration Blender would integrate with by communicating with the extension-client. This will be a new a new section in the user-preferences. - List repos (add/remove support). - List extensions (add/remove support). - Update extensions. ``` extensions/ ├── shared.link ├── localhost/ │ ├── addons │ ├── keymaps │ ├── themes │ └── assets ├── extensions.blender.org/ │ ├── addons/ │ │ ├── fsiddi/ │ │ │ └── light_utils │ │ ├── brecht/ │ │ │ └── cycles_powerdrill │ │ └── blender-studio/ │ │ └── animation_shelf │ ├── themes/ │ │ ├── blender/ │ │ │ ├── blue │ │ │ ├── nitro │ │ │ └── flatty-lite │ │ └── venomgfx/ │ │ └── flatty-purple │ └── assets └── blendermarket.com/ └── addons/ └── cgcookie/ └── retopo_flow ~/.config/blender/3.6/extensions /usr/share/blender/3.6/extensions ~/.config/blender/3.6/extensions/ ├── shared-studio-addons.txt (supports multiple OSs) ├── fsiddi-local-addons.txt ├── localhost/ │ ├── addons │ ├── keymaps │ ├── themes │ └── assets ├── extensions.blender.org/ │ ├── addons/ │ │ ├── light_utils │ │ ├── cycles_powerdrill │ │ └── animation_shelf │ ├── themes/ │ │ ├── blue │ │ ├── nitro │ │ └── flatty-lite │ └── assets └── blendermarket.com/ └── addons/ └── retopo_flow ``` Implementation -------------- - The extension-client will be managed by Blender as an external process. This avoids common problems integrating non-blocking logic into Blender interfering with Python's internal state and allows for (upgrading multiple extensions at once for e.g.). It also allows simplifies writing tests, allowing TDD. - The extension-client has no stored state (all configuration is passed to it on activation). Again, simplifies running multiple instances at once. - Local extension directories are to be entirely maintained by the extension manager. Meaning users should never manually copy files into this path. Removal of these files upon updating is not considered a bug. To Be Decided ============= - Details of meta-data formats, expected fields ... etc. An extension meta-data (likely a separate file) should contain enough information to display an entry in the interface (name, author(s), description, type, compatibility information). - Details of extension storage, archive format ... etc. - Details of compatibility (only compatible with certain Blender versions), support for multiple Blender versions at once. - It should be possible to install an extension from a URL, providing that URL references a repo currently in use. We might support drag & drop URL's into Blender's to install preferences, details TBD. - Support multiple versions of the same extension (development, stable... etc). - Handling of extensions which include compiled modules. - Support for listing extensions directly from GIT repositories. Note that this is more on the online infrastructure side of things. GIT repositories could be scanned and have their packages automatically built. This could be an experimental option - for users who also run daily builds. - Name-spacing - We may want to namespace extensions so each author has a top-level identifier. - How add-ons handle name spacing needs some investigation, e.g. ``bl_addons.{repo}.{add_on}``. - Storage - The local extension should not store configuration as we want to be able to uninstall/reinstall without loosing anything of value to the user. - We may want to support a generic API for extensions to have a storage location for their own persistent data. Further Work ============ - Automatic updates (optional). This requires some investigation, even if updating can be automatic - the thing that's updated may be in-use. So user interaction may be required to explicitly disable the add-on, update and enable it. - Security (see below). - Installing/upgrading extensions from the command line, e.g. ``blender --extensions-upgrade-all``. - Privacy: consider approaches like using DNS for update checking that can't be used to track users, or at least have a public documented policy to not collect user info when doing this. Security -------- From discussion with Brecht and Francesco, we had some initial discussion around security, this is a summary of what we thought made sense. - Domain allow-listing - Blender will maintain a list of accepted domains and provide a Python API to access this list. - Add-ons are expected to check with this list before accessing online content (we may have a way to accept accessing a domain in the UI). - While we cannot enforce rules around accessing online content (such attempts are easy to by-pass). Intentionally bypassing these checks may result in the add-on being explicitly blocked. Note that we might have some limited enforcement of accepted URL's for common API's (requests for e.g.) that a developer would have to intentionally subvert - however this not a core requirement. - Malicious extension blocking As part of updating ``blender.org`` extensions, a list of known malicious extensions will be checked, where Blender reserves the right to disable an extension that is known to be malicious. Repositories can maintian their own malicious extension list as well. The user will be notified of this with a message for why the extension of what was disabled. Examples of malicious extensions include but are not limited to: - Extensions that install viruses/malware. - Extensions that bypass network access mechanisms (phone home without user consent). - Malicious repo blocking We may also want to support this.