imaginary

repository·master·Indexed 26 days ago

https://github.com/h2non/imaginary

A fast HTTP microservice written in Go for high-level image processing. Backed by libvips and bimg, it provides high-performance transformations including resizing, cropping, and format conversion with a low memory footprint. Features include a transformation pipeline, URL signatures for security, remote HTTP URL source support, and placeholder image responses.

Tokens
11.4K
Snippets
26
Records
70
Agent score
91%

What's inside imaginary

  1. Enable URL signatures for security

    master
    To protect against multiple image operation attacks and verify requester identity, you can enable URL signatures (URL-safe Base64-encoded HMAC digests) using the -enable-url-signature flag. This requires a signature key provided via the -url-signature-key flag or the URL_SIGNATURE_KEY environment variable.
  2. Ingest Imaginary logs with Fluentd

    master

    Imaginary uses an Apache-compatible log format. You can ingest these logs using Fluentd by applying a parser filter to separate access logs from warning/error logs.

    Access logs (containing a code field) will be tagged with *.imaginary.access, while warning and error logs (lacking a code field) will be tagged with *.imaginary.error.

    # use your own tag name (*.imaginary for this example)
    <filter *.imaginary>
        @type parser
        key_name log
        reserve_data true
    
        <parse>
            @type multi_format
            # access logs parser
            <pattern>
                format regexp
                expression /^[^ ]* [^ ]* [^ ]* \[(?<time>[^\]]*)\] "(?<method>\S+)(?: +(?<path>[^ ]*) +\S*)?" (?<code>[^ ]*) (?<size>[^ ]*) (?<response_time>[^ ]*)$/
                types code:integer,size:integer,response_time:float
                time_key time
                time_format %d/%b/%Y %H:%M:%S
            </pattern>
            # warnings / error logs parser
            <pattern>
                format none
                message_key message
            </pattern>
        </parse>
    </filter>
    
    <match *.imaginary>
        @type rewrite_tag_filter
    
        # Logs with code field are access logs, and logs without are error logs
        <rule>
            key code
            pattern ^.+$
            tag ${tag}.access
        </rule>
        <rule>
            key code
            pattern ^.+$
            invert true
            tag ${tag}.error
        </rule>
    </match>
  3. Deploy imaginary to Cloud Foundry

    master

    To deploy to Cloud Foundry (Bluemix/Pivotal), follow these steps:

    1. Clone the repository.
    2. Push the application using the specific buildpack.
    3. Set the LD_LIBRARY_PATH to point to the vips library.
    4. Start the application.
    git clone https://github.com/h2non/imaginary.git
    
    cf push -b https://github.com/yacloud-io/go-buildpack-imaginary.git imaginary-inst01 --no-start
    
    cf set-env imaginary-inst01 LD_LIBRARY_PATH /home/vcap/app/vendor/vips/lib
    
    cf start imaginary-inst01
  4. Configure remote URL image source

    master

    To allow imaginary to fetch images from remote HTTP URLs (using the ?url=http://... query parameter), you must enable the -enable-url-source flag.

    Additional security and control options for remote sources:

    • Restrict Origins: Use -allowed-origins <urls> (comma-separated) to restrict which hosts/paths can be used as sources.
    • Auth Forwarding: Use -enable-auth-forwarding to forward X-Forward-Authorization or Authorization headers from the client to the image source server.
    • Static Authorization: Use -authorization <value> to define a constant Authorization header sent to all image source servers, overwriting forwarding behavior.
    • Size Limits: Use -max-allowed-size <bytes> to restrict the maximum size of the remote image source.
  5. Enable API Authorization with a Key

    master

    You can enable simple token-based authorization by passing the -key flag to the imaginary binary. Once enabled, the API key can be provided in requests via either the API-Key HTTP header or a key query parameter.

    POST /crop HTTP/1.1
    Host: localhost:8088
    API-Key: secret
  6. Configure image placeholder responses

    master

    When -enable-placeholder is active, imaginary returns a placeholder image instead of an error for bad requests or server errors. The placeholder is dynamically resized and converted to match the requested width, height, and image type.

    To use a custom placeholder image, use the -placeholder <path> flag. It is recommended to use a large image (e.g., 1200x1200px) in JPEG, PNG, or WEBP format.

  7. Submit Images via Form Data

    master
    When uploading images using multipart/form-data, you must include at least one field named file containing the raw image data. If you wish to use a different field name, you can specify it using the field parameter.
  8. Configure concurrency throttling for production

    master

    To protect your server from DDoS-like attacks and ensure stable performance in production, use the -concurrency flag. A recommended limit is up to 20 requests per second per server.

    $ imaginary -concurrency 20
  9. Install libvips dependency

    master

    imaginary requires libvips 8.8+ (8.9+ recommended). You can use the following script to install it on OSX, Debian/Ubuntu, Redhat, Fedora, or Amazon Linux. This script requires curl and pkg-config to be installed on your system.

    curl -s https://raw.githubusercontent.com/h2non/bimg/master/preinstall.sh | sudo bash -
  10. Configure Allowed Origins for Image URLs

    master
    To prevent unauthorized image fetching, imaginary can be configured to only allow requests where the image source URL matches a specified list of origins. This is done using the -allowed-origins flag. The validation checks if the remote URL matches the hostname and path of at least one origin in the list, supporting wildcards.