lobo/zfin
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Change candle TTL to 23h, 45m for cron jitter/update README
All checks were successful
Generic zig build / build (push) Successful in 40s
Details

Browse source
This commit is contained in:
Emil Lerch 2026-03-11 11:26:09 -07:00
parent d25d6acb9b
commit e6ff204a54
Signed by: lobo
GPG key ID: A7B62D657EF764F8
2 changed files with 18 additions and 18 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

24
README.md
View file

@ -35,7 +35,7 @@ zfin aggregates data from multiple free-tier APIs. Each provider is used for the
| Data type | Provider | Auth | Free-tier limit | Cache TTL |
|-----------------------|---------------|------------------------|----------------------------|--------------|
| Daily candles (OHLCV) | TwelveData | `TWELVEDATA_API_KEY` | 8 req/min, 800/day | 24 hours |
| Daily candles (OHLCV) | TwelveData | `TWELVEDATA_API_KEY` | 8 req/min, 800/day | 23h45m |
| Real-time quotes | TwelveData | `TWELVEDATA_API_KEY` | 8 req/min, 800/day | Never cached |
| Dividends | Polygon | `POLYGON_API_KEY` | 5 req/min | 14 days |
| Splits | Polygon | `POLYGON_API_KEY` | 5 req/min | 14 days |
@ -75,10 +75,9 @@ zfin aggregates data from multiple free-tier APIs. Each provider is used for the
**Used for:** earnings calendar (historical and upcoming).
- Endpoint: `https://finnhub.io/api/v1/calendar/earnings`
- Endpoint: `https://api.finnhub.io/api/v1/calendar/earnings`
- Free tier: 60 requests per minute.
- Fetches 5 years back and 1 year forward from today.
- Note: Finnhub requires TLS 1.2. Since Zig's HTTP client only supports TLS 1.3, requests to Finnhub automatically fall back to system `curl`.
### Alpha Vantage
@ -123,7 +122,7 @@ Cache files use [SRF](https://github.com/lobo/srf) (Simple Record Format), a lin
| Data type | TTL | Rationale |
|---------------|--------------|--------------------------------------------------|
| Daily candles | 24 hours | Only changes once per trading day |
| Daily candles | 23h45m | Slightly under 24h for cron jitter tolerance |
| Dividends | 14 days | Declared well in advance |
| Splits | 14 days | Rare corporate events |
| Options | 1 hour | Prices change continuously during market hours |
@ -495,9 +494,7 @@ src/
portfolio.zig Lots, positions, and portfolio aggregation
classification.zig Classification metadata parser
quote.zig Real-time quote data
ticker_info.zig Security metadata
providers/
provider.zig Type-erased provider interface (vtable)
twelvedata.zig TwelveData: candles, quotes
polygon.zig Polygon: dividends, splits
finnhub.zig Finnhub: earnings
@ -512,12 +509,15 @@ src/
cache/
store.zig SRF file cache with TTL freshness checks
net/
http.zig HTTP client with retries and TLS 1.2 fallback
http.zig HTTP client with retries and server error retry
rate_limiter.zig Token-bucket rate limiter
cli/
main.zig CLI entry point and all commands
commands/
common.zig Shared CLI helpers (progress, formatting)
perf.zig Trailing returns command
quote.zig Quote command
... (14 command files)
tui.zig Interactive TUI application
tui/
main.zig Interactive TUI application
chart.zig z2d pixel chart renderer (Kitty graphics)
keybinds.zig Configurable keybinding system
theme.zig Configurable color theme
@ -533,8 +533,8 @@ accounts.srf Account to tax type mapping for analysis
### Dependencies
| Dependency | Source | Purpose |
|----------------------------------------------------|---------------------|--------------------------------------------------|
| [SRF](https://github.com/lobo/srf) | Local (`../../srf`) | Cache file format and portfolio/watchlist parsing |
|----------------------------------------------------|---------------------|---------------------------------------------------|
| [SRF](https://git.lerch.org/lobo/srf) | Git | Cache file format and portfolio/watchlist parsing |
| [libvaxis](https://github.com/rockorager/libvaxis) | Git (v0.5.1) | Terminal UI rendering |
## Building

4
src/cache/store.zig vendored
View file

@ -21,8 +21,8 @@ pub const Ttl = struct {
const s_per_day = std.time.s_per_day;
/// Historical candles older than 1 day never expire
pub const candles_historical: i64 = -1; // infinite
/// Latest day's candle refreshes every 24h
pub const candles_latest: i64 = s_per_day;
/// Latest day's candle refreshes every 23h45m (15-min buffer for cron jitter)
pub const candles_latest: i64 = s_per_day - 15 * std.time.s_per_min;
/// Dividend data refreshes biweekly
pub const dividends: i64 = 14 * s_per_day;
/// Split data refreshes biweekly