mirror of
https://github.com/Xevion/time-banner.git
synced 2025-12-05 23:16:35 -06:00
86 lines
4.0 KiB
Markdown
86 lines
4.0 KiB
Markdown
# time-banner
|
|
|
|
Dynamically generated timestamp images
|
|
|
|
## Routes
|
|
|
|
`GET /[relative|absolute]/[value]{.ext}?tz={timezone}&format={format_string}&now={timestamp}&static={boolean}`
|
|
|
|
- [x] `{relative|absolute}` - The display format of the time.
|
|
- [x] `{value}` - The time value to work with. Relative values can be specified by prefixing with `+` or `-`.
|
|
- [ ] Relative values are relative to the value acquired from the `now` parameter (which defaults to the current time).
|
|
- Whether the value is relative or absolute has nothing to do with the display format.
|
|
- [x] `/absolute/+0` will display the current time in UTC.
|
|
- [ ] Note: The `now` parameter is returned in the `Date` response header.
|
|
- [x] `Accept` or `{.ext}` - Determines the output format. If not specified, `.svg` is assumed.
|
|
- [ ] `Accept` requires a valid MIME type.
|
|
- [x] `.ext` requires a valid extension.
|
|
- [ ] Supported values: `.png`/`image/png`,
|
|
- [ ] `X-Timezone` or `?tz={timezone}` - The timezone to display the time in. If not specified, UTC is assumed.
|
|
- [ ] `auto` will attempt to determine the timezone from the client's IP address. Depending on currently unknown factors, this may be disregarded.
|
|
- [ ] Return detected timezone in `X-Timezone` response header.
|
|
- [ ] `?format={format}` - The format of the time to display. If not specified, `%Y-%m-%d %H:%M:%S %Z` is assumed.
|
|
- [ ] Only relevant for `absolute` values.
|
|
- [ ] `X-Date-Now` or `?now={timestamp}` - The timestamp to use for relative time calculations. If not specified, the current time is used.
|
|
- [ ] `?static={boolean}` - Whether to redirect to a static version of the URL. Useful for creating specific URLs manually.
|
|
- [ ] If a value is not passed, (`?static`), `true` is assumed. Anything other than `true`, `1` or `yes` (case-insensitive) is considered `false`.
|
|
- [ ] Some header values will be translated to query parameters if provided (not `Accept`).
|
|
- [ ] e.g. `/rel/+3600.png?static&now=1752170474` will redirect to `/relative/1752174074.png`
|
|
- [x] `/favicon.ico` - Returns a dynamic favicon of an analog clock.
|
|
- [ ] Uses naive timestamp from `X-Date-Now` if provided.
|
|
- [ ] Uses timezone from `X-Timezone` if provided.
|
|
- [ ] Uses IP geolocation to determine timezone if neither is provided.
|
|
|
|
### Examples
|
|
|
|
```
|
|
/1752170474 => 2025-07-10 12:01:14 UTC
|
|
/abs/1752170474 => 2025-07-10 12:01:14 UTC
|
|
/absolute/+3600 => 2025-07-10 13:01:14 UTC
|
|
/abs/-1800 => 2025-07-10 11:01:14 UTC
|
|
/rel/1752170474 => 15 minutes ago
|
|
/rel/+3600 => 1 hour from now
|
|
/relative/-1800 => 30 minutes ago
|
|
/relative/1752170474.png?tz=America/Chicago => 2025-07-10 06:01:14 CDT
|
|
/relative/1752170474?type=relative => 2081-01-17 12:02:28 PM
|
|
```
|
|
|
|
## Ideas
|
|
|
|
- Frontend with React for Demo
|
|
- Refetch favicon every 10 minutes
|
|
- Click to copy image URLs
|
|
- Dynamic Examples
|
|
- Dynamic light/dark mode
|
|
- `?theme={auto|light|dark}`, default `light`
|
|
- Customizable SVG templates
|
|
- Dynamic favicon generation
|
|
- Clock svg optimized for favicon size
|
|
- Move hands to the current time
|
|
- Use geolocation of request IP to determine timezone
|
|
- Advanced: create sun/moon SVG based on local time
|
|
- Support for different timezone formats in query parameters or headers
|
|
- `?tz=...` or `X-Timezone: ...`
|
|
- `CST` or `America/Chicago` or `UTC-6` or `GMT-6` or `-0600`
|
|
- Automatically guessed based on geolocation of source IP address
|
|
- Complex caching abilities
|
|
- Multi-level caching (disk with max size, memory)
|
|
- Automatic expiry of relative items
|
|
- Use browser cache headers
|
|
- Detect force refreshs and allow cache busting
|
|
- `Accept` header support
|
|
- IP-based rate limiting
|
|
- Multi-domain rate limiting factors
|
|
- Computational cost: 1ms = 1 token, max 100 tokens per minute
|
|
- Base rate: 3 requests per second
|
|
- Cached Conversions
|
|
- If PNG is cached, then JPEG/WEBP/etc. can be converted from cached PNG
|
|
- Additional date input formats
|
|
- 2025-07-10-12:01:14
|
|
- 2025-07-10-12:01
|
|
- 2025-07-10-12:01:14-06:00
|
|
- 2025-07-10-12:01:14-06
|
|
- 2025-07-10-12:01:14-06:00:00
|
|
- 2025-07-10-12:01:14-06:00:00.000
|
|
- 2025-07-10-12:01:14-06:00:00Z-06:00
|