Files
sorsfonalak/services/horoscope-api/src/natal.rs
T
fecoandClaude Opus 5.5 3a84110565 Add horoscope-api, synastry, and backend services
- horoscope-api: Swiss Ephemeris natal charts, timezone/place resolution,
  POST /v1/natal and POST /v1/synastry
- backend: users with roles, email/password and Google login, saved charts,
  synastries and invites, analyses with credit ledger, public shares, admin
- shared crates: astro-engine, db (migrations), horoscope-client, service-kit
- docker-compose with postgres, legacy Java project for reference

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012vLHzh5qUhFtmJhzkcTbXL
2026-11-15 10:25:35 +00:00

436 lines
17 KiB
Rust

//! `POST /v1/natal`: birth data -> place -> time zone -> UTC -> chart.
use astro_engine::time::{is_valid_julian_date, jd_from_unix_seconds, julian_to_gregorian};
use astro_engine::{ChartInput, ChartOptions, GeoPosition, NatalChart, calculate_chart};
use geo_tz::tz::parse_offset;
use geo_tz::{AmbiguityPolicy, Country, GeoError, LocalizedTime, Place, PlaceMatch, ZoneChoice, ZoneSource};
use jiff::civil::{Date, DateTime, Time};
use jiff::tz::Offset;
use serde::{Deserialize, Serialize};
use crate::AppState;
use crate::error::ApiError;
/// Coordinates farther than this from every known place of the given country
/// are probably a mistake (wrong country or swapped latitude/longitude).
const FAR_FROM_COUNTRY_KM: f64 = 150.0;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum Calendar {
#[default]
Gregorian,
/// Julian calendar date (e.g. Russia before 1918); converted to Gregorian.
Julian,
}
#[derive(Debug, Clone, Deserialize, Serialize)]
#[serde(deny_unknown_fields)]
pub struct NatalRequest {
/// Optional label, echoed back.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub name: Option<String>,
/// Local birth date, `YYYY-MM-DD`.
pub date: String,
/// Local birth time, `HH:MM` or `HH:MM:SS`; omit if unknown.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub time: Option<String>,
#[serde(default)]
pub calendar: Calendar,
/// Country of birth: ISO 3166-1 alpha-2/alpha-3 code or English name.
pub country: String,
/// Place name (any language, accents optional).
#[serde(default, skip_serializing_if = "Option::is_none")]
pub place: Option<String>,
/// First-level region (county/state) to disambiguate `place`.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub region: Option<String>,
/// Exact GeoNames id (e.g. from `GET /v1/places`); takes precedence over `place`.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub geonames_id: Option<u64>,
/// Coordinates override the place's coordinates; required without a place.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub latitude: Option<f64>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub longitude: Option<f64>,
/// Meters; used only for topocentric positions.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub elevation: Option<f64>,
/// IANA time zone override (e.g. `Europe/Budapest`).
#[serde(default, skip_serializing_if = "Option::is_none")]
pub timezone: Option<String>,
/// Fixed UTC offset override (e.g. `+02:00`) when the historical record
/// says so; disables time zone rules.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub utc_offset: Option<String>,
/// Handling of local times that occurred twice or not at all due to DST.
#[serde(default)]
pub ambiguous_time: AmbiguityPolicy,
#[serde(default)]
pub options: ChartOptions,
}
#[derive(Debug, Serialize)]
pub struct LocationInfo {
pub country: Country,
#[serde(skip_serializing_if = "Option::is_none")]
pub place: Option<Place>,
pub latitude: f64,
pub longitude: f64,
pub elevation: f64,
/// `place` or `coordinates`: where latitude/longitude come from.
pub coordinates_source: &'static str,
/// Nearest known populated place when only coordinates were given.
#[serde(skip_serializing_if = "Option::is_none")]
pub nearest_place: Option<NearestPlace>,
/// Other places matching the name (when `place` was ambiguous).
#[serde(skip_serializing_if = "Vec::is_empty")]
pub alternatives: Vec<PlaceMatch>,
}
#[derive(Debug, Serialize)]
pub struct NearestPlace {
#[serde(flatten)]
pub place: Place,
pub distance_km: f64,
}
#[derive(Debug, Serialize)]
pub struct TimeInfo {
pub calendar: Calendar,
/// Date as given in the request.
pub date_as_given: String,
/// Gregorian date used for the calculation.
pub date: String,
pub time_known: bool,
#[serde(flatten)]
pub localized: LocalizedTime,
pub zone_source: Option<ZoneSource>,
/// Local mean time at the birth longitude (UT + longitude/15).
pub local_mean_time: String,
#[serde(skip_serializing_if = "Vec::is_empty")]
pub notes: Vec<String>,
}
#[derive(Debug, Serialize)]
pub struct DataSources {
pub ephemeris: astro_engine::EphemerisInfo,
pub tzdb_version: String,
pub geonames_downloaded: Option<String>,
pub geonames_attribution: &'static str,
}
#[derive(Debug, Serialize)]
pub struct Meta {
pub service: &'static str,
pub version: &'static str,
pub data_sources: DataSources,
}
/// One person's chart with the resolved place and time.
#[derive(Debug, Serialize)]
pub struct NatalResult {
pub input: NatalRequest,
pub location: LocationInfo,
pub time: TimeInfo,
#[serde(flatten)]
pub chart: NatalChart,
pub warnings: Vec<String>,
}
#[derive(Debug, Serialize)]
pub struct NatalResponse {
#[serde(flatten)]
pub result: NatalResult,
pub meta: Meta,
}
pub fn meta(state: &AppState) -> Meta {
Meta {
service: env!("CARGO_PKG_NAME"),
version: env!("CARGO_PKG_VERSION"),
data_sources: DataSources {
ephemeris: state.engine.info(),
tzdb_version: state.atlas.zones.version.clone(),
geonames_downloaded: state.atlas.places.downloaded.clone(),
geonames_attribution: "Place data from GeoNames (https://www.geonames.org), CC BY 4.0",
},
}
}
fn bad(msg: impl Into<String>) -> ApiError {
ApiError::BadRequest(msg.into())
}
fn parse_date(text: &str, calendar: Calendar) -> Result<Date, ApiError> {
let parts: Vec<&str> = text.trim().split('-').collect();
let [y, m, d] = parts.as_slice() else {
return Err(bad(format!("date must be YYYY-MM-DD, got '{text}'")));
};
let (Ok(y), Ok(m), Ok(d)) = (y.parse::<i32>(), m.parse::<u32>(), d.parse::<u32>()) else {
return Err(bad(format!("date must be YYYY-MM-DD, got '{text}'")));
};
if !(1000..=2999).contains(&y) {
return Err(bad("year must be between 1000 and 2999"));
}
let (y, m, d) = match calendar {
Calendar::Gregorian => (y, m, d),
Calendar::Julian => {
if !is_valid_julian_date(y, m, d) {
return Err(bad(format!("'{text}' is not a valid Julian calendar date")));
}
julian_to_gregorian(y, m, d)
}
};
Date::new(y as i16, m as i8, d as i8).map_err(|_| bad(format!("'{text}' is not a valid date")))
}
fn parse_time(text: &str) -> Result<Time, ApiError> {
let err = || bad(format!("time must be HH:MM or HH:MM:SS, got '{text}'"));
let nums: Vec<i8> = text.trim().split(':').map(|p| p.parse::<i8>().map_err(|_| err())).collect::<Result<_, _>>()?;
let (h, m, s) = match nums.as_slice() {
[h, m] => (*h, *m, 0),
[h, m, s] => (*h, *m, *s),
_ => return Err(err()),
};
Time::new(h, m, s, 0).map_err(|_| err())
}
fn validate_coordinates(lat: f64, lon: f64) -> Result<(), ApiError> {
if !(-90.0..=90.0).contains(&lat) || !lat.is_finite() {
return Err(bad(format!("latitude must be between -90 and 90, got {lat}")));
}
if !(-180.0..=180.0).contains(&lon) || !lon.is_finite() {
return Err(bad(format!("longitude must be between -180 and 180, got {lon}")));
}
Ok(())
}
/// Finds the birth place: GeoNames id > place name; returns the best match and
/// the remaining candidates.
fn resolve_place(
state: &AppState,
req: &NatalRequest,
country: &Country,
warnings: &mut Vec<String>,
) -> Result<(Option<Place>, Vec<PlaceMatch>), ApiError> {
if let Some(id) = req.geonames_id {
let place = state.atlas.places.by_id(id)?;
if place.country_code != country.iso2 {
return Err(GeoError::PlaceCountryMismatch {
id,
place: place.name.clone(),
actual: place.country_code.clone(),
expected: country.iso2.clone(),
}
.into());
}
return Ok((Some(place.clone()), Vec::new()));
}
let Some(query) = req.place.as_deref().filter(|q| !q.trim().is_empty()) else {
return Ok((None, Vec::new()));
};
let mut matches = state.atlas.places.search(country, query, req.region.as_deref(), 6);
if matches.is_empty() {
if req.latitude.is_some() && req.longitude.is_some() {
warnings
.push(format!("Place '{query}' was not found in {}; the given coordinates are used.", country.name));
return Ok((None, Vec::new()));
}
// Suggest places from the whole country with a prefix of the query.
let prefix: String = query.chars().take(4).collect();
let suggestions = state.atlas.places.search(country, &prefix, None, 5);
return Err(ApiError::PlaceNotFound { query: query.into(), country: country.name.clone(), suggestions });
}
let best = matches.remove(0);
if !matches.is_empty() {
warnings.push(format!(
"'{query}' matches {} places in {}; the most likely one was used ({}{}). \
Pass geonames_id or region to choose another (see location.alternatives).",
matches.len() + 1,
country.name,
best.place.name,
best.place.region.as_deref().map(|r| format!(", {r}")).unwrap_or_default(),
));
}
Ok((Some(best.place), matches))
}
pub fn calculate(state: &AppState, req: NatalRequest) -> Result<NatalResult, ApiError> {
let mut warnings = Vec::new();
let mut notes = Vec::new();
// --- date and time -------------------------------------------------------
let date = parse_date(&req.date, req.calendar)?;
let time_known = req.time.as_deref().is_some_and(|t| !t.trim().is_empty());
let time = match req.time.as_deref().filter(|t| !t.trim().is_empty()) {
Some(t) => parse_time(t)?,
None => Time::constant(12, 0, 0, 0),
};
let local = DateTime::from_parts(date, time);
if req.calendar == Calendar::Julian {
notes.push(format!("Julian calendar date {} converted to Gregorian {date}.", req.date.trim()));
}
let orb_multiplier = req.options.orb_multiplier;
if !(orb_multiplier > 0.0 && orb_multiplier <= 3.0) {
return Err(bad("options.orb_multiplier must be greater than 0 and at most 3"));
}
// --- place ----------------------------------------------------------------
let country = state.atlas.places.country(&req.country)?.clone();
let (place, alternatives) = resolve_place(state, &req, &country, &mut warnings)?;
let (latitude, longitude, coordinates_source) = match (req.latitude, req.longitude, &place) {
(Some(lat), Some(lon), _) => (lat, lon, "coordinates"),
(None, None, Some(p)) => (p.latitude, p.longitude, "place"),
(Some(_), None, _) | (None, Some(_), _) => {
return Err(bad("latitude and longitude must be given together"));
}
(None, None, None) => return Err(bad("either place, geonames_id or latitude+longitude is required")),
};
validate_coordinates(latitude, longitude)?;
let elevation = req.elevation.or(place.as_ref().and_then(|p| p.elevation.map(f64::from))).unwrap_or(0.0);
let nearest_place = if place.is_none() {
state.atlas.places.nearest(&country.iso2, latitude, longitude, |_| true).map(|(p, d)| {
if d > FAR_FROM_COUNTRY_KM {
warnings.push(format!(
"The coordinates are {d:.0} km from the nearest known place in {} ({}); check the country and \
the coordinates (latitude/longitude swapped?).",
country.name, p.name
));
}
NearestPlace { place: p.clone(), distance_km: (d * 10.0).round() / 10.0 }
})
} else {
None
};
// --- time zone ------------------------------------------------------------
if req.utc_offset.is_some() && req.timezone.is_some() {
return Err(bad("give either timezone or utc_offset, not both"));
}
let (mut localized, zone_source) = match req.utc_offset.as_deref() {
Some(text) => {
let seconds = parse_offset(text).ok_or_else(|| bad(format!("invalid utc_offset '{text}'")))?;
notes
.push("A fixed UTC offset from the request was used; time zone and DST rules were not applied.".into());
(state.atlas.zones.localize_fixed(local, seconds)?, None)
}
None => {
let ZoneChoice { zone, source } =
state.atlas.choose_zone(&country, req.timezone.as_deref(), place.as_ref(), (latitude, longitude))?;
if source == ZoneSource::Request
&& !state.atlas.zones.zones_of(&country.iso2).iter().any(|z| z.name == zone)
{
warnings.push(format!("Time zone {zone} is not one of the zones of {}.", country.name));
}
(state.atlas.zones.localize(&zone, local, req.ambiguous_time)?, Some(source))
}
};
if let Some(t) = &localized.transition {
warnings.push(format!(
"The local time falls into a DST {} ({} -> {}); resolved with '{}'.",
match t.kind {
geo_tz::TransitionKind::Gap => "gap (non-existent hour)",
geo_tz::TransitionKind::Fold => "fold (repeated hour)",
},
t.offset_before,
t.offset_after,
serde_json::to_value(t.resolved_with).ok().and_then(|v| v.as_str().map(str::to_owned)).unwrap_or_default(),
));
}
if localized.abbreviation == "LMT" && localized.zone.is_some() {
// Before standard time, clocks (and birth records) showed the local
// mean time of the place itself; tzdb only knows the LMT of the zone's
// reference city (e.g. Budapest for all of Hungary).
let zone_lmt = localized.utc_offset.clone();
let place_offset = (longitude * 240.0).round() as i32;
let zone = localized.zone.take();
localized = state.atlas.zones.localize_fixed(local, place_offset)?;
localized.zone = zone;
localized.abbreviation = "LMT".into();
notes.push(format!(
"No standard time was in use yet: local mean time of the birthplace (longitude {longitude:.4}°, \
UTC{}) was used instead of the zone's reference-city LMT (UTC{zone_lmt}).",
localized.utc_offset
));
}
if date.year() < 1970 && localized.zone.is_some() {
notes.push(
"Time zone history before 1970 comes from the IANA tzdb backzone data; verify unusual local practices \
(e.g. wartime or regional deviations) against birth records and use utc_offset if they differ."
.into(),
);
}
// --- chart ----------------------------------------------------------------
let ts = localized.timestamp;
let jd_ut = jd_from_unix_seconds(ts.as_second() as f64 + ts.subsec_nanosecond() as f64 * 1e-9);
let observer = GeoPosition { latitude, longitude, elevation };
let input = ChartInput { jd_ut, observer, time_known, options: req.options };
let mut chart = calculate_chart(state.engine.as_ref(), &input).map_err(|e| ApiError::Calculation(e.to_string()))?;
warnings.append(&mut chart.warnings);
if let Some((from, to)) = state.engine.info().precise_years
&& !(from..=to).contains(&(date.year() as i32))
{
warnings.push(format!("The date is outside the {from}-{to} range of the installed ephemeris files."));
}
let lmt_seconds = ts.as_second() + (longitude * 240.0).round() as i64;
let local_mean_time = Offset::UTC
.to_datetime(jiff::Timestamp::from_second(lmt_seconds).map_err(|e| ApiError::Internal(e.to_string()))?)
.time()
.to_string();
Ok(NatalResult {
time: TimeInfo {
calendar: req.calendar,
date_as_given: req.date.trim().to_string(),
date: date.to_string(),
time_known,
localized,
zone_source,
local_mean_time,
notes,
},
location: LocationInfo {
country,
place,
latitude,
longitude,
elevation,
coordinates_source,
nearest_place,
alternatives,
},
chart,
warnings,
input: req,
})
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn dates() {
assert_eq!(parse_date("1985-07-14", Calendar::Gregorian).unwrap().to_string(), "1985-07-14");
assert_eq!(parse_date("1917-10-25", Calendar::Julian).unwrap().to_string(), "1917-11-07");
assert!(parse_date("1985-02-30", Calendar::Gregorian).is_err());
assert!(parse_date("1900-02-29", Calendar::Gregorian).is_err());
assert!(parse_date("1900-02-29", Calendar::Julian).is_ok());
assert!(parse_date("14.07.1985", Calendar::Gregorian).is_err());
assert!(parse_date("0999-01-01", Calendar::Gregorian).is_err());
}
#[test]
fn times() {
assert_eq!(parse_time("14:30").unwrap().to_string(), "14:30:00");
assert_eq!(parse_time("07:05:09").unwrap().to_string(), "07:05:09");
assert!(parse_time("24:00").is_err());
assert!(parse_time("14").is_err());
}
}