|
1 | | -#ImageCompression Service Documentation |
| 1 | +#ImageOptimizer Service Documentation |
2 | 2 |
|
3 | 3 | ##Overview |
4 | | -This serviceallows users to download and compress images fromprovided URLs. It supportsdifferentimage formats such asJPEG, PNG, and WebP, withoptionalresizing and qualityadjustments. Theserver listens for HTTP GET requests, processes the images, and returns the compressed image files. |
| 4 | +The Image Optimizer Serviceallows users to download and compress images fromspecified URLs. It supportsa variety ofimage formats, includingJPEG, PNG, and WebP, withadditional features forresizing and qualityadjustment. Theservice also caches compressed images to avoid redundant processing, improving performance. |
5 | 5 |
|
6 | | -###Features: |
7 | | -- Supports JPEG, PNG,andWebP formats. |
8 | | --Imageresizing based oncustom resolution. |
9 | | --Image quality adjustment forJPEG. |
10 | | -- Caching based on MD5hash to avoidredundant compression. |
11 | | -- Domain whitelisting to controlwhich sources areallowedforimagedownload. |
| 6 | +###KeyFeatures: |
| 7 | +- Supportsmultiple image formats:JPEG, PNG, WebP. |
| 8 | +-Allows customresizing based onuser-provided resolution. |
| 9 | +-AdjustableJPEG quality. |
| 10 | +- Cachingsystembased on MD5hashing to avoidduplicate processing. |
| 11 | +- Domain whitelisting to control allowed imagesources. |
12 | 12 |
|
13 | 13 | --- |
14 | 14 |
|
15 | 15 | ##Installation |
16 | 16 |
|
17 | 17 | ###Prerequisites: |
18 | | --Go 1.18 or later. |
19 | | -- Required Gopackages: |
20 | | --`github.com/gorilla/mux` |
21 | | --`github.com/chai2010/webp` |
22 | | --`github.com/nfnt/resize` |
| 18 | +-**Go version**: 1.18 or later. |
| 19 | +- Required Golibraries: |
| 20 | +-`github.com/gorilla/mux` for routing. |
| 21 | +-`github.com/chai2010/webp` for WebP image handling. |
| 22 | +-`github.com/nfnt/resize` for resizing functionality. |
23 | 23 |
|
24 | | -###Clone the repository: |
25 | | -```bash |
26 | | -git clone<repo_url> |
27 | | -``` |
| 24 | +###Steps: |
28 | 25 |
|
29 | | -###Install dependencies: |
30 | | -```bash |
31 | | -go get github.com/gorilla/mux |
32 | | -go get github.com/chai2010/webp |
33 | | -go get github.com/nfnt/resize |
34 | | -``` |
| 26 | +1.**Clone the repository:** |
| 27 | +```bash |
| 28 | + git clone<repo_url> |
| 29 | +``` |
35 | 30 |
|
36 | | -###Build the service: |
37 | | -```bash |
38 | | -go build -o image-compressor |
39 | | -``` |
| 31 | +2.**Install dependencies:** |
| 32 | +```bash |
| 33 | + go get github.com/gorilla/mux |
| 34 | + go get github.com/chai2010/webp |
| 35 | + go get github.com/nfnt/resize |
| 36 | +``` |
| 37 | + |
| 38 | +3.**Build the application:** |
| 39 | +```bash |
| 40 | + go build -o image-compressor |
| 41 | +``` |
40 | 42 |
|
41 | 43 | --- |
42 | 44 |
|
43 | 45 | ##Usage |
44 | 46 |
|
45 | | -###CommandLineFlags |
46 | | --`-o` (default:`.`): Specifies the output directoryfor compressed images. |
47 | | --`-p` (default:`8080`):Specifies the porton whichtheserver listens. |
| 47 | +###Command-LineOptions: |
| 48 | +-`-o` (default:`.`): Specifies the output directorywhere compressed images will be saved. |
| 49 | +-`-p` (default:`8080`):Defines the port theservice listens on. |
48 | 50 | -`-s` (default:`*`): Comma-separated list of allowed domains for downloading images. Use`*` to allow all domains. |
49 | 51 |
|
50 | 52 | Example: |
51 | 53 | ```bash |
52 | 54 | ./image-compressor -o ./compressed-images -p 8080 -s example.com,another.com |
53 | 55 | ``` |
54 | 56 |
|
55 | | -###Endpoints |
| 57 | +###APIEndpoints |
56 | 58 |
|
57 | 59 | ####1.**GET /optimize** |
58 | | -This endpoint compresses theimage fromthe given URL,applying optionalresizing andquality adjustments. If the compressed image already exists,it is served directlywithoutreprocessing. |
| 60 | +Compresses animage froma provided URL,optionallyresizing andadjusting the quality. If the compressed image already exists,the cached version is returnedwithoutrecompression. |
59 | 61 |
|
60 | 62 | #####Query Parameters: |
61 | | --**url** (required): TheimageURL to download and compress. |
62 | | --**output** (optional):Output imageformat (`jpeg`,`png`,`webp`). Defaults to the format of the original image. |
63 | | --**quality** (optional): JPEG quality (1-100). Onlyapplies to JPEGformat. Defaults to 75. |
64 | | --**resolution** (optional): Desired resolution in the format`widthxheight`. Use`auto` for either width or height to maintain aspect ratio. Example:`800x600`,`auto x 600`. |
65 | | --**v** (optional): Versioning parameterusedtotrigger new compression if image parametershave changed. |
| 63 | +-**url** (required): The URL of the image to download and compress. |
| 64 | +-**output** (optional):The desired outputformat (`jpeg`,`png`,`webp`). Defaults to theoriginalformat of the image. |
| 65 | +-**quality** (optional): JPEG quality (1-100). Onlyapplicable to JPEGimages. Default is 75. |
| 66 | +-**resolution** (optional): Desiredimageresolution in the format`widthxheight`. Use`auto` for either width or height to maintain aspect ratio. Example:`800x600`,`auto x 600`. |
| 67 | +-**v** (optional): Versioning parameter toforce new compression if image parameterschange. |
66 | 68 |
|
67 | 69 | #####Example: |
68 | 70 | ``` |
69 | 71 | GET /optimize?url=https://example.com/image.jpg&output=webp&quality=80&resolution=800x600&v=1 |
70 | 72 | ``` |
71 | 73 |
|
| 74 | +#####Response: |
| 75 | +Returns the compressed image in the specified format or the original format if none is specified. |
| 76 | + |
| 77 | +--- |
| 78 | + |
72 | 79 | ####2.**GET /optimize/{filename}** |
73 | | -This endpoint retrieves an existingcompressed image by its filename. |
| 80 | +Fetches a previouslycompressed image by its filename (typically the MD5 hash of the image parameters). |
74 | 81 |
|
75 | 82 | #####Example: |
76 | 83 | ``` |
77 | 84 | GET /optimize/abcd1234.jpeg |
78 | 85 | ``` |
79 | 86 |
|
| 87 | +#####Response: |
| 88 | +Returns the requested image file from the output directory. |
| 89 | + |
| 90 | +--- |
| 91 | + |
80 | 92 | ####3.**GET /** |
81 | | -A basic health check endpoint thatreturns`"ok!"`. |
| 93 | +A basic health check endpointto confirmthatthe server is running. Returns`"ok!"`. |
82 | 94 |
|
83 | 95 | #####Example: |
84 | 96 | ``` |
85 | 97 | GET / |
86 | 98 | ``` |
87 | 99 |
|
| 100 | +#####Response: |
| 101 | +``` |
| 102 | +ok! |
| 103 | +``` |
| 104 | + |
88 | 105 | --- |
89 | 106 |
|
90 | 107 | ##How It Works |
91 | 108 |
|
92 | | -###Image Download |
93 | | -The`downloadImage` functiondownloads the image from theprovided URL, checks its format,and decodes it into an image object. Supported formatsare JPEG, PNG, and WebP. |
| 109 | +###1.**Image Download** |
| 110 | +Theservicedownloads the image from thespecified URLand decodes it into an`image.Image` object. Supported formatsinclude JPEG, PNG, and WebP. |
94 | 111 |
|
95 | | -###Compression |
96 | | -The`compressImage` function resizes the image based onthe providedresolutionand compresses it based on the chosen format. For JPEG, quality adjustments are possible. |
| 112 | +###2.**ImageCompression** |
| 113 | +Thedownloaded image can be resized based onuser-specifiedresolutionparameters. For JPEGs, quality adjustment is supported. After processing, the image is saved in the desired format. |
97 | 114 |
|
98 | | -###MD5 Hashing |
99 | | -The imageprocessing parameters (URL, output format, quality, resolution,version) are concatenated into a single string and hashed using MD5togenerate a unique filename for the compressed image. |
| 115 | +###3.**MD5 Hashing for Caching** |
| 116 | +To avoid redundantprocessing, the service generates an MD5 hash based on the imageURL,desiredoutput format, quality, resolution,and versioning parameters. This hash is usedtocreate a unique filename for the compressed image. If the file already exists, the cached version is returned. |
100 | 117 |
|
101 | | -###FileCaching |
102 | | -If the compressed imagefilealready exists, the service retrieves it directly from theoutput directory, avoiding redundant downloadsandcompressions. |
| 118 | +###4.**Caching and Performance** |
| 119 | +If the compressed image already exists in the output directory, the service retrievesand returnsit directly, bypassing theneed to download and process the image again. This caching mechanism significantly improves performanceandreduces redundant computation. |
103 | 120 |
|
104 | 121 | --- |
105 | 122 |
|
106 | 123 | ##Error Handling |
107 | | -- If the domain of the image URL is not allowed, the service responds with a`403 Forbidden` error. |
108 | | -- If the image format is unsupported or any other error occurs during image processing, the service responds with a`500 Internal Server Error`. |
| 124 | + |
| 125 | +-**403 Forbidden:** Returned if the domain of the image URL is not on the allowed list (`-s` parameter). |
| 126 | +-**500 Internal Server Error:** Occurs if an unsupported image format is provided or an error occurs during the image processing stage. |
109 | 127 |
|
110 | 128 | --- |
111 | 129 |
|
112 | 130 | ##Example Workflow |
113 | 131 |
|
114 | | -1.**Download andCompress Image:** |
| 132 | +1.**Download andcompress an image:** |
115 | 133 | ```bash |
116 | 134 | curl"http://localhost:8080/optimize?url=https://example.com/image.jpg&output=png&resolution=800x600&quality=90&v=1" |
117 | 135 | ``` |
118 | 136 |
|
119 | | -2.**RetrieveExisting Compressed Image:** |
| 137 | +2.**Retrievean existing compressed image:** |
120 | 138 | ```bash |
121 | 139 | curl"http://localhost:8080/optimize/<md5-hash>.png" |
122 | 140 | ``` |
123 | 141 |
|
124 | 142 | --- |
125 | 143 |
|
126 | 144 | ##License |
127 | | -This project is open source and available under the[MIT License](LICENSE). |
| 145 | +This project is licensed under the[MIT License](LICENSE). |
| 146 | + |
| 147 | +--- |
| 148 | + |
| 149 | +###Contributions |
| 150 | +Feel free to contribute to this project by submitting issues or pull requests on the official repository. |