Mirror/brk
1
0
Fork 0
mirror of https://github.com/bitcoinresearchkit/brk.git synced 2026-05-29 20:59:27 -07:00
Code Issues Packages Projects Releases Wiki Activity

global: snapshot

Browse Source
This commit is contained in:
nym21
2026-03-10 01:13:52 +01:00
parent 961dea6934
commit 46ac55d950
121 changed files with 9792 additions and 5997 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
crates/brk_server/src/api/metrics/bulk.rs
View File

@@ -31,6 +31,7 @@ pub async fn handler(
let format = resolved.format();
let etag = resolved.etag();
let csv_filename = resolved.csv_filename();
if headers.has_etag(etag.as_str()) {
return Ok((StatusCode::NOT_MODIFIED, "").into_response());
@@ -55,8 +56,8 @@ pub async fn handler(
h.insert_cache_control(CACHE_CONTROL);
match format {
Format::CSV => {
h.insert_content_disposition_attachment();
h.insert_content_type_text_csv()
h.insert_content_disposition_attachment(&csv_filename);
h.insert_content_type_text_csv();
}
Format::JSON => h.insert_content_type_application_json(),
}

5
crates/brk_server/src/api/metrics/data.rs
View File

@@ -31,6 +31,7 @@ pub async fn handler(
let format = resolved.format();
let etag = resolved.etag();
let csv_filename = resolved.csv_filename();
if headers.has_etag(etag.as_str()) {
return Ok((StatusCode::NOT_MODIFIED, "").into_response());
@@ -55,8 +56,8 @@ pub async fn handler(
h.insert_cache_control(CACHE_CONTROL);
match format {
Format::CSV => {
h.insert_content_disposition_attachment();
h.insert_content_type_text_csv()
h.insert_content_disposition_attachment(&csv_filename);
h.insert_content_type_text_csv();
}
Format::JSON => h.insert_content_type_application_json(),
}

8
crates/brk_server/src/api/metrics/legacy.rs
View File

@@ -15,6 +15,8 @@ use crate::{
extended::HeaderMapExtended,
};
const SUNSET: &str = "2027-01-01T00:00:00Z";
use super::AppState;
pub async fn handler(
@@ -31,6 +33,7 @@ pub async fn handler(
let format = resolved.format();
let etag = resolved.etag();
let csv_filename = resolved.csv_filename();
if headers.has_etag(etag.as_str()) {
return Ok((StatusCode::NOT_MODIFIED, "").into_response());
@@ -55,11 +58,12 @@ pub async fn handler(
h.insert_cache_control(CACHE_CONTROL);
match format {
Format::CSV => {
h.insert_content_disposition_attachment();
h.insert_content_type_text_csv()
h.insert_content_disposition_attachment(&csv_filename);
h.insert_content_type_text_csv();
}
Format::JSON => h.insert_content_type_application_json(),
}
h.insert_deprecation(SUNSET);
Ok(response)
}

6
crates/brk_server/src/api/metrics/mod.rs
View File

@@ -14,7 +14,7 @@ use brk_types::{
MetricSelection, MetricSelectionLegacy, MetricWithIndex, Metrics, PaginatedMetrics, Pagination,
};
use crate::{CacheStrategy, extended::TransformResponseExtended};
use crate::{CacheStrategy, Error, extended::TransformResponseExtended};
use super::AppState;
@@ -244,7 +244,9 @@ impl ApiMetricsRoutes for ApiRouter<AppState> {
let ser_index = split.next().unwrap();
let Ok(index) = Index::try_from(ser_index) else {
return format!("Index {ser_index} doesn't exist").into_response();
return Error::not_found(
format!("Index '{ser_index}' doesn't exist")
).into_response();
};
let params = MetricSelection::from((

59
crates/brk_server/src/api/openapi/mod.rs
View File

@@ -14,7 +14,7 @@ mod compact;
pub use compact::ApiJson;
use aide::openapi::{Contact, Info, License, OpenApi, Tag};
use aide::openapi::{Contact, Info, License, OpenApi, Server, ServerVariable, Tag};
use crate::VERSION;
@@ -31,6 +31,34 @@ pub fn create_openapi() -> OpenApi {
- **Multiple formats**: JSON and CSV output
- **LLM-optimized**: [`/llms.txt`](/llms.txt) for discovery, [`/api.json`](/api.json) compact OpenAPI spec for tool use (full spec at [`/openapi.json`](/openapi.json))
### Quick start
```bash
curl -s https://bitview.space/api/block-height/0
curl -s https://bitview.space/api/metrics/search/price
curl -s https://bitview.space/api/metric/price/day1
```
### Errors
All errors return structured JSON with a consistent format:
```json
{
"error": {
"type": "not_found",
"code": "metric_not_found",
"message": "'foo' not found, did you mean 'bar'?",
"doc_url": "https://bitcoinresearchkit.org/api"
}
}
```
- **`type`**: Error category — `invalid_request` (400), `forbidden` (403), `not_found` (404), `unavailable` (503), or `internal` (500)
- **`code`**: Machine-readable error code (e.g. `invalid_address`, `metric_not_found`, `weight_exceeded`)
- **`message`**: Human-readable description
- **`doc_url`**: Link to API documentation
### Client Libraries
- [JavaScript](https://www.npmjs.com/package/brk-client)
@@ -130,9 +158,38 @@ pub fn create_openapi() -> OpenApi {
},
];
let servers = vec![Server {
url: "{scheme}://{host}".into(),
description: Some("BRK server".into()),
variables: [
(
"scheme".into(),
ServerVariable {
enumeration: vec!["https".into(), "http".into()],
default: "https".into(),
description: Some("Protocol".into()),
..Default::default()
},
),
(
"host".into(),
ServerVariable {
default: "bitview.space".into(),
description: Some(
"Server address (e.g. bitview.space or localhost:3110)".into(),
),
..Default::default()
},
),
]
.into(),
..Default::default()
}];
OpenApi {
info,
tags,
servers,
..OpenApi::default()
}
}

30
crates/brk_server/src/api/server/mod.rs
View File

@@ -5,10 +5,9 @@ use axum::{
extract::State,
http::{HeaderMap, Uri},
};
use brk_types::{DiskUsage, Health, Height, SyncStatus};
use vecdb::ReadableVec;
use brk_types::{DiskUsage, Health, SyncStatus};
use crate::{CacheStrategy, extended::TransformResponseExtended};
use crate::{CacheStrategy, VERSION, extended::TransformResponseExtended};
use super::AppState;
@@ -26,23 +25,7 @@ impl ServerRoutes for ApiRouter<AppState> {
state
.cached_json(&headers, CacheStrategy::Height, &uri, move |q| {
let indexed_height = q.height();
let tip_height = tip_height?;
let blocks_behind = Height::from(tip_height.saturating_sub(*indexed_height));
let last_indexed_at_unix = q
.indexer()
.vecs
.blocks
.timestamp
.collect_one(indexed_height).unwrap();
Ok(SyncStatus {
indexed_height,
tip_height,
blocks_behind,
last_indexed_at: last_indexed_at_unix.to_iso8601(),
last_indexed_at_unix,
})
Ok(q.sync_status(tip_height?))
})
.await
},
@@ -89,12 +72,19 @@ impl ServerRoutes for ApiRouter<AppState> {
get_with(
async |State(state): State<AppState>| -> axum::Json<Health> {
let uptime = state.started_instant.elapsed();
let tip_height = state.client.get_last_height();
let sync = state.sync(|q| {
let tip_height = tip_height.unwrap_or(q.indexed_height());
q.sync_status(tip_height)
});
axum::Json(Health {
status: Cow::Borrowed("healthy"),
service: Cow::Borrowed("brk"),
version: Cow::Borrowed(VERSION),
timestamp: jiff::Timestamp::now().to_string(),
started_at: state.started_at.to_string(),
uptime_seconds: uptime.as_secs(),
sync,
})
},
|op| {

156
crates/brk_server/src/error.rs
View File

@@ -1,58 +1,162 @@
use axum::{
http::StatusCode,
http::{StatusCode, header},
response::{IntoResponse, Response},
};
use brk_error::Error as BrkError;
use schemars::JsonSchema;
use serde::Serialize;
use crate::extended::HeaderMapExtended;
/// Server result type with Error that implements IntoResponse.
pub type Result<T> = std::result::Result<T, Error>;
/// Server error type that maps to HTTP status codes.
pub struct Error(StatusCode, String);
const DOC_URL: &str = "/api";
#[derive(Serialize, JsonSchema)]
pub(crate) struct ErrorBody {
error: ErrorDetail,
}
#[derive(Serialize, JsonSchema)]
struct ErrorDetail {
/// Error category: "invalid_request", "forbidden", "not_found", "unavailable", or "internal"
#[schemars(with = "String")]
r#type: &'static str,
/// Machine-readable error code (e.g. "invalid_address", "metric_not_found")
#[schemars(with = "String")]
code: &'static str,
/// Human-readable description
message: String,
/// Link to API documentation
#[schemars(with = "String")]
doc_url: &'static str,
}
fn error_type(status: StatusCode) -> &'static str {
match status {
StatusCode::BAD_REQUEST => "invalid_request",
StatusCode::FORBIDDEN => "forbidden",
StatusCode::NOT_FOUND => "not_found",
StatusCode::SERVICE_UNAVAILABLE => "unavailable",
_ => "internal",
}
}
fn error_status(e: &BrkError) -> StatusCode {
match e {
BrkError::InvalidTxid
| BrkError::InvalidNetwork
| BrkError::InvalidAddress
| BrkError::UnsupportedType(_)
| BrkError::Parse(_)
| BrkError::NoMetrics
| BrkError::MetricUnsupportedIndex { .. }
| BrkError::WeightExceeded { .. } => StatusCode::BAD_REQUEST,
BrkError::UnknownAddress
| BrkError::UnknownTxid
| BrkError::NotFound(_)
| BrkError::MetricNotFound(_) => StatusCode::NOT_FOUND,
BrkError::AuthFailed => StatusCode::FORBIDDEN,
BrkError::MempoolNotAvailable => StatusCode::SERVICE_UNAVAILABLE,
_ => StatusCode::INTERNAL_SERVER_ERROR,
}
}
fn error_code(e: &BrkError) -> &'static str {
match e {
BrkError::InvalidAddress => "invalid_address",
BrkError::InvalidTxid => "invalid_txid",
BrkError::InvalidNetwork => "invalid_network",
BrkError::UnsupportedType(_) => "unsupported_type",
BrkError::Parse(_) => "parse_error",
BrkError::NoMetrics => "no_metrics",
BrkError::MetricUnsupportedIndex { .. } => "metric_unsupported_index",
BrkError::WeightExceeded { .. } => "weight_exceeded",
BrkError::UnknownAddress => "unknown_address",
BrkError::UnknownTxid => "unknown_txid",
BrkError::NotFound(_) => "not_found",
BrkError::MetricNotFound(_) => "metric_not_found",
BrkError::MempoolNotAvailable => "mempool_not_available",
BrkError::AuthFailed => "auth_failed",
_ => "internal_error",
}
}
fn build_error_body(status: StatusCode, code: &'static str, message: String) -> Vec<u8> {
serde_json::to_vec(&ErrorBody {
error: ErrorDetail {
r#type: error_type(status),
code,
message,
doc_url: DOC_URL,
},
})
.unwrap()
}
/// Server error type that maps to HTTP status codes and structured JSON.
pub struct Error {
status: StatusCode,
code: &'static str,
message: String,
}
impl Error {
pub(crate) fn new(status: StatusCode, code: &'static str, msg: impl Into<String>) -> Self {
Self {
status,
code,
message: msg.into(),
}
}
pub fn bad_request(msg: impl Into<String>) -> Self {
Self(StatusCode::BAD_REQUEST, msg.into())
Self::new(StatusCode::BAD_REQUEST, "bad_request", msg)
}
pub fn forbidden(msg: impl Into<String>) -> Self {
Self(StatusCode::FORBIDDEN, msg.into())
Self::new(StatusCode::FORBIDDEN, "forbidden", msg)
}
pub fn not_found(msg: impl Into<String>) -> Self {
Self(StatusCode::NOT_FOUND, msg.into())
Self::new(StatusCode::NOT_FOUND, "not_found", msg)
}
pub fn internal(msg: impl Into<String>) -> Self {
Self(StatusCode::INTERNAL_SERVER_ERROR, msg.into())
Self::new(StatusCode::INTERNAL_SERVER_ERROR, "internal_error", msg)
}
pub(crate) fn into_response_with_etag(self, etag: &str) -> Response {
let mut response = self.into_response();
let headers = response.headers_mut();
headers.insert_etag(etag);
headers.insert_cache_control_must_revalidate();
response
}
}
impl From<BrkError> for Error {
fn from(e: BrkError) -> Self {
let status = match &e {
BrkError::InvalidTxid
| BrkError::InvalidNetwork
| BrkError::InvalidAddress
| BrkError::UnsupportedType(_)
| BrkError::Parse(_)
| BrkError::NoMetrics
| BrkError::MetricUnsupportedIndex { .. }
| BrkError::WeightExceeded { .. } => StatusCode::BAD_REQUEST,
BrkError::UnknownAddress
| BrkError::UnknownTxid
| BrkError::NotFound(_)
| BrkError::MetricNotFound { .. } => StatusCode::NOT_FOUND,
_ => StatusCode::INTERNAL_SERVER_ERROR,
};
Self(status, e.to_string())
Self {
status: error_status(&e),
code: error_code(&e),
message: e.to_string(),
}
}
}
impl IntoResponse for Error {
fn into_response(self) -> Response {
(self.0, self.1).into_response()
let body = build_error_body(self.status, self.code, self.message);
(
self.status,
[(header::CONTENT_TYPE, "application/json")],
body,
)
.into_response()
}
}

16
crates/brk_server/src/extended/header_map.rs
View File

@@ -10,12 +10,14 @@ pub trait HeaderMapExtended {
fn insert_cache_control(&mut self, value: &str);
fn insert_cache_control_must_revalidate(&mut self);
fn insert_content_disposition_attachment(&mut self);
fn insert_content_disposition_attachment(&mut self, filename: &str);
fn insert_content_type_application_json(&mut self);
fn insert_content_type_text_csv(&mut self);
fn insert_content_type_text_plain(&mut self);
fn insert_content_type_octet_stream(&mut self);
fn insert_deprecation(&mut self, sunset: &'static str);
}
impl HeaderMapExtended for HeaderMap {
@@ -36,8 +38,11 @@ impl HeaderMapExtended for HeaderMap {
self.insert_cache_control("public, max-age=1, must-revalidate");
}
fn insert_content_disposition_attachment(&mut self) {
self.insert(header::CONTENT_DISPOSITION, "attachment".parse().unwrap());
fn insert_content_disposition_attachment(&mut self, filename: &str) {
self.insert(
header::CONTENT_DISPOSITION,
format!("attachment; filename=\"{filename}\"").parse().unwrap(),
);
}
fn insert_content_type_application_json(&mut self) {
@@ -58,4 +63,9 @@ impl HeaderMapExtended for HeaderMap {
"application/octet-stream".parse().unwrap(),
);
}
fn insert_deprecation(&mut self, sunset: &'static str) {
self.insert("Deprecation", "true".parse().unwrap());
self.insert("Sunset", sunset.parse().unwrap());
}
}

35
crates/brk_server/src/extended/result.rs
View File

@@ -1,11 +1,10 @@
use axum::{http::StatusCode, response::Response};
use brk_error::{Error, Result};
use axum::response::Response;
use brk_error::Result;
use serde::Serialize;
use crate::extended::ResponseExtended;
use crate::{Error, extended::ResponseExtended};
pub trait ResultExtended<T> {
fn with_status(self) -> Result<T, (StatusCode, String)>;
fn to_json_response(self, etag: &str) -> Response
where
T: Serialize;
@@ -18,29 +17,13 @@ pub trait ResultExtended<T> {
}
impl<T> ResultExtended<T> for Result<T> {
fn with_status(self) -> Result<T, (StatusCode, String)> {
self.map_err(|e| {
(
match e {
Error::InvalidTxid
| Error::InvalidNetwork
| Error::InvalidAddress
| Error::UnsupportedType(_) => StatusCode::BAD_REQUEST,
Error::UnknownAddress | Error::UnknownTxid => StatusCode::NOT_FOUND,
_ => StatusCode::INTERNAL_SERVER_ERROR,
},
e.to_string(),
)
})
}
fn to_json_response(self, etag: &str) -> Response
where
T: Serialize,
{
match self.with_status() {
match self {
Ok(value) => Response::new_json(&value, etag),
Err((status, message)) => Response::new_json_with(status, &message, etag),
Err(e) => Error::from(e).into_response_with_etag(etag),
}
}
@@ -48,9 +31,9 @@ impl<T> ResultExtended<T> for Result<T> {
where
T: AsRef<str>,
{
match self.with_status() {
match self {
Ok(value) => Response::new_text(value.as_ref(), etag),
Err((status, message)) => Response::new_text_with(status, &message, etag),
Err(e) => Error::from(e).into_response_with_etag(etag),
}
}
@@ -58,9 +41,9 @@ impl<T> ResultExtended<T> for Result<T> {
where
T: Into<Vec<u8>>,
{
match self.with_status() {
match self {
Ok(value) => Response::new_bytes(value.into(), etag),
Err((status, message)) => Response::new_bytes_with(status, message.into_bytes(), etag),
Err(e) => Error::from(e).into_response_with_etag(etag),
}
}
}

10
crates/brk_server/src/extended/transform_operation.rs
View File

@@ -3,6 +3,8 @@ use aide::transform::{TransformOperation, TransformResponse};
use axum::Json;
use schemars::JsonSchema;
use crate::error::ErrorBody;
pub trait TransformResponseExtended<'t> {
fn addresses_tag(self) -> Self;
fn blocks_tag(self) -> Self;
@@ -99,13 +101,13 @@ impl<'t> TransformResponseExtended<'t> for TransformOperation<'t> {
}
fn bad_request(self) -> Self {
self.response_with::<400, Json<String>, _>(|res| {
self.response_with::<400, Json<ErrorBody>, _>(|res| {
res.description("Invalid request parameters")
})
}
fn not_found(self) -> Self {
self.response_with::<404, Json<String>, _>(|res| res.description("Resource not found"))
self.response_with::<404, Json<ErrorBody>, _>(|res| res.description("Resource not found"))
}
fn not_modified(self) -> Self {
@@ -115,6 +117,8 @@ impl<'t> TransformResponseExtended<'t> for TransformOperation<'t> {
}
fn server_error(self) -> Self {
self.response_with::<500, Json<String>, _>(|res| res.description("Internal server error"))
self.response_with::<500, Json<ErrorBody>, _>(|res| {
res.description("Internal server error")
})
}
}

49
crates/brk_server/src/lib.rs
View File

@@ -85,11 +85,50 @@ impl Server {
},
);
let response_uri_layer = axum::middleware::from_fn(
let response_time_layer = axum::middleware::from_fn(
async |request: Request<Body>, next: Next| -> Response<Body> {
let uri = request.uri().clone();
let start = Instant::now();
let mut response = next.run(request).await;
response.extensions_mut().insert(uri);
response.headers_mut().insert(
"X-Response-Time",
format!("{}us", start.elapsed().as_micros())
.parse()
.unwrap(),
);
response
},
);
// Wrap non-JSON client errors (e.g. axum extraction rejections) in structured JSON
let json_error_layer = axum::middleware::from_fn(
async |request: Request<Body>, next: Next| -> Response<Body> {
use axum::http::header::CONTENT_TYPE;
use axum::response::IntoResponse;
let response = next.run(request).await;
if !response.status().is_client_error()
|| response
.headers()
.get(CONTENT_TYPE)
.is_some_and(|v| v.as_bytes().starts_with(b"application/json"))
{
return response;
}
let (parts, body) = response.into_parts();
let bytes = axum::body::to_bytes(body, 4096)
.await
.unwrap_or_default();
let msg = String::from_utf8_lossy(&bytes).to_string();
let code = if parts.status == StatusCode::NOT_FOUND {
"not_found"
} else {
"bad_request"
};
let mut response = Error::new(parts.status, code, msg).into_response();
response.extensions_mut().extend(parts.extensions);
response
},
);
@@ -99,7 +138,8 @@ impl Server {
.on_response(
|response: &Response<Body>, latency: Duration, _: &tracing::Span| {
let status = response.status().as_u16();
let uri = response.extensions().get::<Uri>().unwrap();
let unknown = Uri::from_static("/unknown");
let uri = response.extensions().get::<Uri>().unwrap_or(&unknown);
match response.status() {
StatusCode::OK => info!(status, %uri, ?latency),
StatusCode::NOT_MODIFIED
@@ -125,10 +165,11 @@ impl Server {
let router = router
.with_state(state)
.merge(website_router)
.layer(CatchPanicLayer::new())
.layer(json_error_layer)
.layer(compression_layer)
.layer(response_uri_layer)
.layer(response_time_layer)
.layer(trace_layer)
.layer(CatchPanicLayer::new())
.layer(TimeoutLayer::with_status_code(
StatusCode::GATEWAY_TIMEOUT,
Duration::from_secs(5),