WIP: Blender Extensions Project #106254

New Issue

Campbell Barton · 2023-03-29T06:15:47+02:00

Campbell Barton commented

2023-03-29 06:15:47 +02:00

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 candidates for installation).
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 packages.

Checks could include:
- Versions always increase and follow semver spec.
- Code checks (Python code byte-code compiles for e.g.).
- Warn on inclusion of __pycache__, *.blend1 files (for e.g.).
- Warn on inclusion of modified files or files not under version control.
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.

Dependencies

Packages must bundle any 3rd party modules they depend on as WHEEL's.
The package manager is responsible for installing the WHEEL's & uninstalling when they are no longer used (most likely the package meta-data includes bundled WHEEL's and their versions).
Multiple packages may include the same WHEEL, in this case only one of them will be used (as the same WHEEL at the same version should be compatible).
There is no complex dependency handling, in the event two packages use different version of the same WHEEL, there is a conflict - only one of the packages can be installed.

Notes:

Prefer WHEEL's over PIP, since PIP is it's own package manager, it may compile code or do advanced operations that a Blender package manager can't reasonably manage - failures with PIP are likely to require command line access, OK for Python developers but not regular users.
We might consider allowing some minor difference in package versions, as a general rule though - supporting different versions and handling their possible incompatibilities is not a goal.
To avoid unnecessary version-mismatches, we may wish to have a rule of thumb for using the versions of packages available at Blender's release date for e.g.

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.

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.

Proposed Layout:

   ~/.config/blender/3.6/extensions
   /usr/share/blender/3.6/extensions

   Example Layout:

   ~/.config/blender/3.6/extensions/
   ├── shared-studio-addons.txt (supports multiple OSs)
   ├── fsiddi-local-addons.txt
   ├── localhost/
   │   ├── addons
   │   ├── keymaps
   │   ├── themes
   │   └── assets
   ├── blender.org/
   │   ├── addons/
   │   │   ├── light_utils
   │   │   ├── cycles_powerdrill
   │   │   └── animation_shelf
   │   ├── themes/
   │   │   ├── blue
   │   │   ├── nitro
   │   │   └── flatty-lite
   │   └── assets
   └── blendermarket.com/
       └── addons/
           └── retopo_flow

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 candidates for installation). - 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 packages. Checks could include: - Versions always increase and follow ``semver`` spec. - Code checks (Python code byte-code compiles for e.g.). - Warn on inclusion of `__pycache__`, `*.blend1` files (for e.g.). - Warn on inclusion of modified files or files not under version control. - 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. Dependencies ------------ - Packages must bundle any 3rd party modules they depend on as WHEEL's. - The package manager is responsible for installing the WHEEL's & uninstalling when they are no longer used (most likely the package meta-data includes bundled WHEEL's and their versions). - Multiple packages may include the same WHEEL, in this case only one of them will be used (as the same WHEEL at the same version should be compatible). - There is no complex dependency handling, in the event two packages use different version of the same WHEEL, there is a conflict - only one of the packages can be installed. Notes: - Prefer WHEEL's over PIP, since PIP is it's own package manager, it may compile code or do advanced operations that a Blender package manager can't reasonably manage - failures with PIP are likely to require command line access, OK for Python developers but not regular users. - We might consider allowing some minor difference in package versions, as a general rule though - supporting different versions and handling their possible incompatibilities is not a goal. - To avoid unnecessary version-mismatches, we may wish to have a rule of thumb for using the versions of packages available at Blender's release date for e.g. 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``. 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. --- Proposed Layout: ``` ~/.config/blender/3.6/extensions /usr/share/blender/3.6/extensions Example Layout: ~/.config/blender/3.6/extensions/ ├── shared-studio-addons.txt (supports multiple OSs) ├── fsiddi-local-addons.txt ├── localhost/ │ ├── addons │ ├── keymaps │ ├── themes │ └── assets ├── blender.org/ │ ├── addons/ │ │ ├── light_utils │ │ ├── cycles_powerdrill │ │ └── animation_shelf │ ├── themes/ │ │ ├── blue │ │ ├── nitro │ │ └── flatty-lite │ └── assets └── blendermarket.com/ └── addons/ └── retopo_flow ```

❤️ 5 🎉 3

Campbell Barton added the

Type

Design

label 2023-03-29 06:15:47 +02:00

Campbell Barton added this to the Python API project 2023-03-29 06:25:50 +02:00

Campbell Barton added the

Download

What's New

Blender Studio

Manual

Developers Blog

Documentation

Benchmark

Blender Conference

Development Fund

One-time Donations

WIP: Blender Extensions Project #106254

Online Extensions

Initial Proposal

Requirements

Non-Goals

Components

Dependencies

Implementation

To Be Decided

Further Work

Security

Plugget

Overlap with Blender Extensions

Dependency

Security