imageproxy/docs/plugin-design.md

# Plugin Design Doc

**Status:** idea phase, with no immediate timeline for implementation

## Objective

Re-architect imageproxy to use a plugin-based system for most features like transformations, security, and caching.
This should reduce build times and binary sizes in the common case,
and provide a mechanism for users to easily add custom features that would not be added to core for various reasons.

## Background

I created imageproxy to [scratch a personal itch](https://wjn.me/b/J_), I needed a simple way to dynamically resize images for my personal website.
I published it as an open source projects because that's what I do, and I'm happy to see others finding it useful for their needs as well.

But inevitably, with more users came requests for additional features because people have different use cases and requirements.
Some of these requests were relatively minor, and I was happy to add them.
But one of the more common requests was to support different caching backends.
Personally, I still use the on-disk cache, but many people wanted to use redis or a cloud provider like AWS, Azure, or GCP.
For a long time I was resistant to adding support for these, mainly out of concern for inflating build times and binary sizes.
I did eventually relent, and [#49] tracked adding support for the most common backends.

Unfortunately my concerns proved true, and build times are _significantly_ slower (TODO: add concrete numbers) now because of all the additional cloud SDKs that get compiled in.
I don't personally care too much about binary size, since I'm not running in a constrained environment, but these build times are really wearing on me.
Additionally, there are a number of outstanding pull requests for relatively obscure features that I don't really want to have to support in the main project.
And quite honestly, there are a number of obscure features that did get merged in over the years that I kinda wish I could rip back out.

[#49]: https://github.com/willnorris/imageproxy/issues/49

### Plugin support in Go

TODO: talk about options like

- RPC (<https://github.com/hashicorp/go-plugin>)
- pkg/plugin (<https://golang.org/pkg/plugin/>)
- embedded interpreter (<https://github.com/robertkrimen/otto>)
- custom binaries (<https://github.com/mholt/caddy>, <https://caddy.community/t/59>)

Spoiler: I'm planning on following the Caddy approach and using custom binaries.

## Design

I plan to model imageproxy after Caddy, moving all key functionality into separate plugins that register themselves with the server,
and which all compile to a single statically-linked binary.
The core project will provide a great number of plugins to cover all of the existing functionality.
I also expect I'll be much more open to adding plugins for features I may not care as much about personally.
Of course, users can also write their own plugins and link them in without needing to contribute them to core if they don't want to.

I anticipate providing two or three build configurations in core:

- **full** - include all the plugins that are part of core (except where they may conflict)
- **minimal** - some set of minimal features that only includes basic caching options, limited transformation options, etc
- **my personal config** - I'll also definitely have a build that I use personally on my site.
  I may decide to just make that the "minimal" build and perhaps call it something different, rather than have a third configuration.

Custom configurations beyond what is provided by core can be done by creating a minimal main package that imports the plugins you care about
and calling some kind of bootstrap method (similar to [what Caddy now does](https://caddy.community/t/59)).

### Types of plugins

(Initially in no particular order, just capturing thoughts.
Lots to do here in thinking through the use cases and what kind of plugin API we really need to provide.)

See also issues and PRs with [label:plugins][].

[label:plugins]: https://github.com/willnorris/imageproxy/issues?q=label:plugins

#### Caching backend

This is one of the most common feature requests, and is also one of the worst offender for inflating build times
and binary sizes because of the size of the dependencies that are typically required.
The minimal imageproxy build would probably only include the in-memory and on-disk caches.
Anything that talked to an external store (redis, cloud providers, etc) would be pulled out.

#### Transformation engine

Today, imageproxy only performs transformations which can be done with pure Go libraries.
There have been a number of requests (or at least questions) to use something like [vips] or [imagemagick], which are both C libraries.
They provide more options, and (likely) better performance, at the cost of complexity and loss of portability in using cgo.
These would likely replace the entire transformation engine in imageproxy,
so I don't know how they would interact with other plugins that merely extend the main engine (they probably wouldn't be able to interact at all).

[vips]: https://github.com/DAddYE/vips
[imagemagick]: https://github.com/gographics/imagick

#### Transformation options

Today, imageproxy performs minimal transformations, mostly around resizing, cropping, and rotation.
It doesn't support any kind of filters, brightness or contrast adjustment, etc.
There are go libraries for them, they're just outside the scope of what I originally intended imageproxy for.
But I'd be happy to have plugins that do that kind of thing.
These plugins would need to be able to hook into the option parsing engine so that they could register their URL options.

#### Image format support

There have been a number of requests for image format support that require cgo libraries:

- **webp encoding** - needs cgo [#114](https://github.com/willnorris/imageproxy/issues/114)
- **progressive jpegs** - probably needs cgo? [#77](https://github.com/willnorris/imageproxy/issues/77)
- **gif to mp4** - maybe doable in pure go, but probably belongs in a plugin [#136](https://github.com/willnorris/imageproxy/issues/136)
- **HEIF** - formate used by newer iPhones ([HEIF](https://en.wikipedia.org/wiki/High_Efficiency_Image_File_Format))

#### Option parsing

Today, options are specified as the first component in the URL path, but [#66] proposes optionally moving that to a query parameter (for a good reason, actually).
Maybe putting that in core is okay?
Maybe it belongs in a plugin, in which case we'd need to expose an API for replacing the option parsing code entirely.

[#66]: https://github.com/willnorris/imageproxy/pull/66

#### Security options

Some people want to add a host blacklist [#85], refusal to process non-image files [#53] [#119].
I don't think there is an issue for it,
but an early fork of the project added request signing that was compatible with nginx's [secure link module](https://nginx.org/en/docs/http/ngx_http_secure_link_module.html).

[#85]: https://github.com/willnorris/imageproxy/pull/85
[#53]: https://github.com/willnorris/imageproxy/issues/53
[#119]: https://github.com/willnorris/imageproxy/pull/119

### Registering Plugins

Plugins are loaded simply by importing their package.
They should have an `init` func that calls `imageproxy.RegisterPlugin`:

```go
type Plugin struct {
}

func RegisterPlugin(name string, plugin Plugin)
```

Plugins hook into various extension points of imageproxy by implementing appropriate interfaces.
A single plugin can hook into multiple parts of imageproxy by implementing multiple interfaces.

For example, two possible interfaces for security related plugins:

```go
// A RequestAuthorizer determines if a request is authorized to be processed.
// Requests are processed before the remote resource is retrieved.
type RequestAuthorizer interface {
    // Authorize returns an error if the request should not
    // be processed further (for example, it doesn't have a
    // valid signature, is not for a whitelisted host, etc).
    AuthorizeRequest(req *http.Request) error
}

// A ResponseAuthorizer determines if a response from a remote server
// is authorized to be returned.
type ResponseAuthorizer interface {
    // AuthorizeResponse returns an error if a response should not be
    // returned to a client (for example, it is not for an image
    // resource, etc).
    AuthorizeResponse(res http.Response) error
}
```

A hypothetical interface for plugins that transform images:

```go
// An ImageTransformer transforms an image.
type ImageTransformer interface {
   // TransformImage based on the provided options and return the result.
   TransformImage(m image.Image, opt Options) image.Image
}
```

Plugins are additionally responsible for registering any additional command line flags they wish to expose to the user,
as well as storing any global state that would previously have been stored on the Proxy struct.