spectura

= Spectura

Spectura is a microservice for taking screenshots of websites in an Open Graph
compatible format usable for link previews on sites such as Facebook and
LinkedIn.

Spectura takes a `url` and an optional signature `s` as query parameters. The
signature ensures that we only visit pre-approved URLs.

In local testing, `USE_SIGNATURES` is set to false, so you dont need the `s` parameter.

Spectura also takes `expire`. This is so that we don't spend time generating screenshots of expired jobs.
Expire is a unix timestamp in seconds. We return the fallback image if expire is exceeded.

If there is no present `expire` property, we always return the fallback image. This is for backwards compatability reasons.

== Setup

You either need to run a Decap instance manually, or run everything inside
Docker as described xref:run_docker[below].

To run Spectura in Docker, you need Docker version 20.10 or higher.

== Running

=== Basic usage

Assuming that Decap is listening on `localhost:4531`:

[source,shell]
----
go build
USE_SIGNATURES=false ./spectura
----

Then make a GET request on the same host:

[source,shell]
----
curl 'http://localhost:19165/api/spectura/v0/screenshot?url=https%3A%2F%2Fwww.jobindex.dk%2F%3Fspectura%3D1&expire=2000000000' --output screenshot.png
----

=== Inside Docker [[run_docker]]

To run Spectura

[NOTE]
Always run with `--build`

[source,shell]
----
docker compose up --build
----

To test Spectura with `curl`

> Remeber you need to set `&expire=2000000000` or some other time after today. If you don't have expire or expire is earlier than today, you will get the fallback image.

[source,shell]
----
curl 'http://localhost:19165/api/spectura/v0/screenshot?url=https://pyjam.as&expire=2000000000'
----

If you use kitty terminal you can print the image directly in your terminal
[source,shell]
----
curl 'http://localhost:19165/api/spectura/v0/screenshot?url=https://pyjam.as&expire=2000000000' | kitty +kitten icat
----


=== Webhook

To get webhook updates you can set the `WEBHOOK_URL` and the `WEBHOOK_AUTHORIZATION_HEADER`.

The `WEBHOOK_URL` will receive a `POST` request with the `Authorization` header set to the value in `WEBHOOK_AUTHORIZATION_HEADER` and a JSON body looking like this:

----
{
  "EventType": "image_created",
  "URL": "https://pyjam.as",
  "ImageCreated": 1675773692,
  "Expire": 2000000000
}
----

Timestamps are represented as a UNIX seconds in UTC.

Event types contain the same data and are:

* `image_created`,  sent whenever and entry is created
* `image_updated`, sent whenever the image itself of a cache entry is updated.


== Configuration

[cols="3,3,3"]
|===
| Name | Required | Default
| `AUTO_REFRESH_AFTER`
| no
| `6h`

|`REFRESH_TASK_DELAY`
| no
| `5s`

|`BG_RATE_LIMIT_TIME`
| no
| `3h`

|`CACHE_TTL`
| no
| `48h`

| `DECAP_URL`
| no
| `http://localhost:4531`

| `IGNORE_BACKGROUND_REQUESTS`
| no
| `false`

| `MAX_IMAGE_SIZE_MIB`
| no
| `20`

| `SCHEDULE_INTERVAL`
| no
| `5m`

| `SIGNING_KEY`
| if `USE_SIGNATURES`
| no default

| `SIGNING_SECRET`
| if `USE_SIGNATURES`
| no default

| `SIGNING_UNIQUE_NAME`
| no
| `jix_spectura`

| `USE_SIGNATURES`
| no
| `true`

| `WEBHOOK_URL`
| no
| no default

| `WEBHOOK_AUTHORIZATION_HEADER`
| no
| no default

|===

== License

Unless otherwise noted, code in this repository is covered by a BSD 3-Clause
License (see the LICENSE file for details).

Files in the xlib package may contain code written by different authors and
covered by other Open Source licenses. Consult the copyright headers in the
specific files for details.