use std::{
any::Any,
borrow::Cow,
fmt,
io::{self, Read, Write},
panic::{self, AssertUnwindSafe},
sync::Arc,
thread,
time::Instant,
};
use jsonx_lib::Parser;
#[cfg(feature = "tracing")]
use crate::trace::event;
use crate::{
config::{Cancellation, Config, Gate},
error::{CallError, Error},
error_object::{ErrorCode, ErrorObject, clip},
framing::{Decoder, FrameError, Framing},
handles::{Peer, Responder},
id::Id,
limits::Limits,
link::{GateState, Link, Shared},
message::{
Entry, Incoming, Invalid, Message, Notification, Request, Response, decode, read_member_id,
},
queue::Queued,
raw::{Json, Raw},
router::{Context, Event, EventFn, Params, RequestHandler, Router},
sink::Sink,
stats::{Stats, Tally},
trace::call_span,
};
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub enum Flow {
Continue,
Stop,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum End {
Eof,
Stopped,
}
#[derive(Debug)]
pub enum Next<'a> {
Read(&'a mut [u8]),
Stopped,
}
pub struct Endpoint<S, K: Sink> {
shared: Arc<Shared<K>>,
link: Arc<dyn Link>,
router: Router<S>,
state: S,
limits: Limits,
parser: Parser,
gate: Option<Gate>,
cancellation: Option<Cancellation>,
input: Option<Decoder>,
}
impl<S, K: Sink> Endpoint<S, K> {
#[must_use]
pub fn new(sink: K, router: Router<S>, state: S) -> Self {
let config = Config::new();
let shared = Shared::new(sink, &config);
let link: Arc<dyn Link> = Arc::clone(&shared) as Arc<dyn Link>;
Self {
shared,
link,
router,
state,
limits: config.limits,
parser: config.limits.parser(),
gate: config.gate,
cancellation: config.cancellation,
input: None,
}
}
#[must_use]
pub fn with_config(mut self, config: Config) -> Self {
self.shared.lock().configure(&config);
self.limits = config.limits;
self.parser = config.limits.parser();
self.gate = config.gate;
self.cancellation = config.cancellation;
if let Some(decoder) = self.input.take() {
self.input = Some(decoder.carried(decoder.framing(), &self.limits));
}
self
}
#[must_use]
pub fn peer(&self) -> Peer {
Peer::new(Arc::clone(&self.link))
}
#[inline]
#[must_use]
pub const fn state(&self) -> &S {
&self.state
}
#[inline]
pub fn state_mut(&mut self) -> &mut S {
&mut self.state
}
pub fn with_sink<R>(&self, f: impl FnOnce(&mut K) -> R) -> R {
f(self.shared.lock().sink_mut())
}
#[must_use]
pub fn is_closed(&self) -> bool {
self.shared.is_closed()
}
pub fn close(&mut self) {
let drain = self.shared.lock().close();
if let Some(drain) = drain {
drain.wait();
}
}
#[must_use]
pub fn next_deadline(&self) -> Option<Instant> {
self.shared.lock().next_deadline()
}
pub fn expire(&self) {
self.shared.lock().expire();
}
#[must_use]
pub fn stats(&self) -> Stats {
self.shared.lock().stats()
}
pub fn handle(&mut self, body: &[u8]) -> Result<Flow, Error> {
let incoming = decode(body, &self.limits);
self.begin_turn(&tally(&incoming, body.len()))?;
let mut stop = false;
match incoming {
Incoming::Single(entry) => self.dispatch(entry, None, &mut stop),
Incoming::Batch(entries) => {
let owed = entries.iter().filter(|entry| owes_response(entry)).count();
let batch = (owed > 0).then(|| self.shared.lock().open_batch(owed));
for entry in entries {
self.dispatch(entry, batch, &mut stop);
}
}
}
self.end_turn()?;
Ok(if stop { Flow::Stop } else { Flow::Continue })
}
pub fn run<R: Read>(&mut self, mut input: R, framing: Framing) -> Result<End, Error> {
let mut decoder = self.take_decoder(framing);
let result = self.read_loop(&mut decoder, &mut input);
self.settle_input(decoder, &result);
result
}
pub fn run_with<R: Read>(&mut self, decoder: &mut Decoder, mut input: R) -> Result<End, Error> {
let result = self.read_loop(decoder, &mut input);
if !matches!(result, Ok(End::Stopped)) {
self.close();
}
result
}
pub fn next_read(&mut self, framing: Framing) -> Result<Next<'_>, Error> {
if self.is_closed() {
self.input = None;
return Err(self.closed_error());
}
let mut decoder = self.take_decoder(framing);
match self.drain(&mut decoder, false) {
Ok(None) => Ok(Next::Read(self.input.insert(decoder).space())),
Ok(Some(_)) => {
self.input = Some(decoder);
Ok(Next::Stopped)
}
Err(error) => {
self.close();
Err(error)
}
}
}
pub fn commit(&mut self, n: usize) {
if let Some(decoder) = &mut self.input {
decoder.commit(n);
}
}
#[must_use]
pub fn buffered_input(&self) -> usize {
self.input.as_ref().map_or(0, Decoder::buffered)
}
#[cfg(feature = "net")]
pub(crate) fn mid_message(&self) -> bool {
self.input.as_ref().is_some_and(Decoder::in_message)
}
pub fn finish(&mut self) -> Result<End, Error> {
let Some(mut decoder) = self.input.take() else {
if self.is_closed() {
return Err(self.closed_error());
}
self.close();
return Ok(End::Eof);
};
let result = if self.is_closed() {
Err(self.closed_error())
} else {
self.drain(&mut decoder, true)
.map(|end| end.unwrap_or(End::Eof))
};
self.settle_input(decoder, &result);
result
}
fn take_decoder(&mut self, framing: Framing) -> Decoder {
match self.input.take() {
Some(decoder) if decoder.framing() == framing => decoder,
Some(decoder) => decoder.carried(framing, &self.limits),
None => framing.decoder(&self.limits),
}
}
fn settle_input(&mut self, decoder: Decoder, result: &Result<End, Error>) {
if matches!(result, Ok(End::Stopped)) {
self.input = Some(decoder);
} else {
self.close();
}
}
fn read_loop<R: Read>(&mut self, decoder: &mut Decoder, input: &mut R) -> Result<End, Error> {
if self.is_closed() {
return Err(self.closed_error());
}
loop {
if let Some(end) = self.drain(decoder, false)? {
return Ok(end);
}
let space = decoder.space();
if space.is_empty() {
break;
}
let n = match input.read(space) {
Ok(0) => break,
Ok(n) => n,
Err(error) if error.kind() == io::ErrorKind::Interrupted => continue,
Err(error) => return Err(Error::Io(error)),
};
decoder.commit(n);
}
Ok(self.drain(decoder, true)?.unwrap_or(End::Eof))
}
fn drain(&mut self, decoder: &mut Decoder, finishing: bool) -> Result<Option<End>, Error> {
loop {
let next = if finishing {
decoder.finish()
} else {
decoder.next_frame()
};
let flow = match next {
Ok(Some(body)) => self.handle(body)?,
Ok(None) => return Ok(None),
Err(error) if error.is_recoverable() => self.oversized(error)?,
Err(error) => return Err(Error::Frame(error)),
};
if flow == Flow::Stop {
return Ok(Some(End::Stopped));
}
}
}
fn oversized(&mut self, error: FrameError) -> Result<Flow, Error> {
self.begin_turn(&Tally {
invalid: 1,
..Tally::default()
})?;
let answer = ErrorObject::invalid_request(format!("the message is too large: {error}"));
self.answer(None, None, &Err(&answer));
report(
&mut self.router.on_event,
&mut self.state,
&Event::Oversized { error },
);
self.end_turn()?;
Ok(Flow::Continue)
}
fn closed_error(&self) -> Error {
self.shared
.lock()
.take_broken()
.map_or(Error::Closed, Error::Io)
}
fn begin_turn(&self, tally: &Tally) -> Result<(), Error> {
let mut inner = self.shared.lock();
if inner.is_closed() {
return Err(inner.take_broken().map_or(Error::Closed, Error::Io));
}
inner.take_in(tally);
inner.endpoint_thread = Some(thread::current().id());
inner.cork();
inner.expire();
Ok(())
}
fn end_turn(&self) -> Result<(), Error> {
let mut inner = self.shared.lock();
inner.uncork();
inner.endpoint_thread = None;
inner
.take_broken()
.map_or(Ok(()), |error| Err(Error::Io(error)))
}
fn answer(
&self,
id: Option<&Id<'_>>,
batch: Option<u64>,
result: &Result<&Json<'_>, &ErrorObject>,
) {
let _reported_at_turn_end = self.shared.lock().respond(id, batch, *result);
}
fn dispatch(&mut self, entry: Entry<'_>, batch: Option<u64>, stop: &mut bool) {
match entry {
Ok(Message::Request(request)) => self.on_request(request, batch, stop),
Ok(Message::Notification(notification)) => self.on_notification(notification, stop),
Ok(Message::Response(response)) => self.on_response(response),
Err(invalid) => self.on_invalid(&invalid, batch),
}
}
fn on_request(&mut self, request: Request<'_>, batch: Option<u64>, stop: &mut bool) {
let Request { id, method, params } = request;
call_span!("request", method, Some(&id));
match self.admit(&id, &method, batch) {
Admission::Admitted => {}
Admission::Refused(refusal) => {
self.answer(Some(&id), batch, &Err(&refusal));
return;
}
Admission::DuplicateId(refusal) => {
self.answer(None, batch, &Err(&refusal));
report(
&mut self.router.on_event,
&mut self.state,
&Event::Invalid {
error: &refusal,
answered: true,
},
);
return;
}
}
let params = Params::new(params, self.parser);
if let Some(refusal) = self.intercept(&method, Some(&id), ¶ms) {
self.answer(Some(&id), batch, &Err(&refusal));
return;
}
let Some(handler) = self.router.requests.get_mut(&*method) else {
let error = ErrorObject::method_not_found(&method);
let _reported = self.shared.lock().respond(Some(&id), batch, Err(&error));
return;
};
match handler {
RequestHandler::Now(handler) => {
let state = &mut self.state;
let mut cx = Context::new(&self.link, stop, Some(&id), &method);
let outcome = contain(|| handler(state, params, &mut cx));
let error;
let result = match &outcome {
Ok(Ok(value)) => Ok(value),
Ok(Err(refusal)) => Err(refusal),
Err(payload) => {
self.shared.lock().count_panic();
report(
&mut self.router.on_event,
&mut self.state,
&Event::Panicked {
method: &method,
message: &panic_message(payload.as_ref()),
},
);
error = ErrorObject::internal_error("the handler panicked");
Err(&error)
}
};
let _reported = self.shared.lock().respond(Some(&id), batch, result);
}
RequestHandler::Deferred(handler) => {
let owned = id.clone().into_owned();
let token = self.shared.lock().begin_deferred(owned.clone(), batch);
let Some(token) = token else {
let error = ErrorObject::new(
ErrorCode::SERVER_OVERLOADED,
"too many requests are already being answered",
);
let _reported = self.shared.lock().respond(Some(&id), batch, Err(&error));
return;
};
let responder = Responder::new(owned, token, Arc::clone(&self.link));
let state = &mut self.state;
let mut cx = Context::new(&self.link, stop, Some(&id), &method);
if let Err(payload) = contain(|| handler(state, params, &mut cx, responder)) {
self.shared.lock().count_panic();
report(
&mut self.router.on_event,
&mut self.state,
&Event::Panicked {
method: &method,
message: &panic_message(payload.as_ref()),
},
);
}
}
}
}
fn admit(&self, id: &Id<'_>, method: &str, batch: Option<u64>) -> Admission {
let mut inner = self.shared.lock();
if inner.in_flight(id) {
return Admission::DuplicateId(ErrorObject::invalid_request(
"the id is already used by a request still being answered",
));
}
let Some(gate) = self.gate.as_ref() else {
return Admission::Admitted;
};
let opening = method == gate.method;
if !opening && inner.gate != GateState::Open && gate.allows_request(method) {
return Admission::Admitted;
}
let refusal = match &inner.gate {
GateState::Open if opening => {
ErrorObject::invalid_request(format!("`{}` was already received", clip(method)))
}
GateState::Open => return Admission::Admitted,
GateState::Opening(_) if opening => ErrorObject::invalid_request(format!(
"`{}` is already being answered",
clip(method)
)),
GateState::Opening(_) => not_initialized(gate),
GateState::Closed if !opening => not_initialized(gate),
GateState::Closed if batch.is_some() => ErrorObject::invalid_request(format!(
"`{}` cannot be sent in a batch",
clip(method)
)),
GateState::Closed => {
inner.gate = GateState::Opening(id.clone().into_owned());
return Admission::Admitted;
}
};
Admission::Refused(refusal)
}
fn on_notification(&mut self, notification: Notification<'_>, stop: &mut bool) {
let Notification { method, params } = notification;
call_span!("notification", method, None::<&Id<'_>>);
if let Some(cancellation) = &self.cancellation {
if *method == *cancellation.method {
let target = params.as_ref().and_then(|p| {
read_member_id(p.as_str(), &cancellation.id_member, &self.parser)
});
if let Some(target) = target {
if self.shared.lock().cancel_incoming(&target) {
report(
&mut self.router.on_event,
&mut self.state,
&Event::Cancelled { id: &target },
);
}
}
return;
}
}
if let Some(gate) = &self.gate {
if self.shared.lock().gate != GateState::Open && !gate.allows(&method) {
report(
&mut self.router.on_event,
&mut self.state,
&Event::Dropped { method: &method },
);
return;
}
}
let params = Params::new(params, self.parser);
if let Some(refusal) = self.intercept(&method, None, ¶ms) {
report(
&mut self.router.on_event,
&mut self.state,
&Event::Refused {
method: &method,
error: &refusal,
},
);
return;
}
let Some(handler) = self.router.notifications.get_mut(&*method) else {
report(
&mut self.router.on_event,
&mut self.state,
&Event::UnknownNotification { method: &method },
);
return;
};
let state = &mut self.state;
let mut cx = Context::new(&self.link, stop, None, &method);
match contain(|| handler(state, params, &mut cx)) {
Ok(Ok(())) => {}
Ok(Err(error)) => report(
&mut self.router.on_event,
&mut self.state,
&Event::InvalidParams {
method: &method,
error: &error,
},
),
Err(payload) => {
self.shared.lock().count_panic();
report(
&mut self.router.on_event,
&mut self.state,
&Event::Panicked {
method: &method,
message: &panic_message(payload.as_ref()),
},
);
}
}
}
fn intercept(
&mut self,
method: &str,
id: Option<&Id<'_>>,
params: &Params<'_>,
) -> Option<ErrorObject> {
let hook = self.router.intercept.as_mut()?;
let state = &mut self.state;
match contain(|| hook(state, method, id, params)) {
Ok(Ok(())) => None,
Ok(Err(refusal)) => Some(refusal),
Err(payload) => {
self.shared.lock().count_panic();
report(
&mut self.router.on_event,
&mut self.state,
&Event::Panicked {
method,
message: &panic_message(payload.as_ref()),
},
);
Some(ErrorObject::internal_error("the handler panicked"))
}
}
}
fn on_response(&mut self, response: Response<'_>) {
let Response { id, result } = response;
let Some(id) = id else {
if let Err(error) = &result {
report(
&mut self.router.on_event,
&mut self.state,
&Event::PeerError { error },
);
}
return;
};
let settled = match ours(&id) {
Some(number) => {
let outcome = result.map(Raw::into_owned).map_err(CallError::Rejected);
self.shared.lock().settle(number, outcome)
}
None => false,
};
if !settled {
report(
&mut self.router.on_event,
&mut self.state,
&Event::Unmatched { id: &id },
);
}
}
fn on_invalid(&mut self, invalid: &Invalid<'_>, batch: Option<u64>) {
let answered = !invalid.is_response();
if answered {
self.answer(invalid.id(), batch, &Err(invalid.error()));
} else if let Some(number) = invalid.id().and_then(ours) {
let outcome = Err(CallError::InvalidResponse(invalid.error().clone()));
let _settled = self.shared.lock().settle(number, outcome);
}
report(
&mut self.router.on_event,
&mut self.state,
&Event::Invalid {
error: invalid.error(),
answered,
},
);
}
}
impl<S, K: Sink> Drop for Endpoint<S, K> {
fn drop(&mut self) {
self.close();
}
}
impl<S, K: Sink> fmt::Debug for Endpoint<S, K> {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("Endpoint")
.field("router", &self.router)
.field("limits", &self.limits)
.field("gate", &self.gate)
.field("cancellation", &self.cancellation)
.finish_non_exhaustive()
}
}
pub fn serve<R, W>(input: R, output: W, framing: Framing, router: Router<()>) -> Result<End, Error>
where
R: Read,
W: Write + Send + 'static,
{
let sink = Queued::new(output, framing)?;
Endpoint::new(sink, router, ()).run(input, framing)
}
enum Admission {
Admitted,
Refused(ErrorObject),
DuplicateId(ErrorObject),
}
fn owes_response(entry: &Entry<'_>) -> bool {
match entry {
Ok(Message::Request(_)) => true,
Ok(_) => false,
Err(invalid) => !invalid.is_response(),
}
}
fn ours(id: &Id<'_>) -> Option<u64> {
id.as_i64()
.and_then(|n| u64::try_from(n).ok())
.filter(|&n| n > 0)
}
fn not_initialized(gate: &Gate) -> ErrorObject {
ErrorObject::new(
gate.code,
format!(
"`{}` must succeed before any other request",
clip(&gate.method)
),
)
}
#[cfg(feature = "tracing")]
fn trace_event(event: &Event<'_>) {
match event {
Event::Panicked { method, message } => {
event!(error, method = ?clip(method), panic = ?message, "a handler panicked");
}
Event::Invalid { error, answered } => {
event!(debug, code = error.code().0, message = ?error.message(), answered, "a malformed message");
}
Event::UnknownNotification { method } => {
event!(debug, method = ?clip(method), "a notification with no handler");
}
Event::Dropped { method } => {
event!(debug, method = ?clip(method), "a notification dropped before the gate opened");
}
Event::Unmatched { id } => {
event!(debug, id = ?clip(&id.to_string()), "a response to no outstanding request");
}
Event::PeerError { error } => {
event!(
warn,
code = error.code().0,
"the peer could not read a message"
);
}
Event::Oversized { error } => {
event!(warn, error = %error, "an oversized message was skipped");
}
Event::Cancelled { id } => {
event!(debug, id = ?clip(&id.to_string()), "the peer cancelled a request");
}
Event::Refused { method, error } => {
event!(debug, method = ?clip(method), code = error.code().0, "a notification was refused by the interceptor");
}
Event::InvalidParams { method, error } => {
event!(debug, method = ?clip(method), message = ?error.message(), "a notification's params did not fit its handler");
}
}
}
#[cfg(not(feature = "tracing"))]
fn trace_event(_event: &Event<'_>) {}
fn contain<T>(f: impl FnOnce() -> T) -> Result<T, Box<dyn Any + Send>> {
panic::catch_unwind(AssertUnwindSafe(f))
}
fn panic_message(payload: &(dyn Any + Send)) -> Cow<'_, str> {
if let Some(text) = payload.downcast_ref::<&str>() {
clip(text)
} else if let Some(text) = payload.downcast_ref::<String>() {
clip(text)
} else {
Cow::Borrowed("(a panic payload that is not text)")
}
}
fn tally(incoming: &Incoming<'_>, bytes: usize) -> Tally {
let mut tally = Tally {
body: true,
bytes,
..Tally::default()
};
let mut count = |entry: &Entry<'_>| match entry {
Ok(Message::Request(_)) => tally.requests += 1,
Ok(Message::Notification(_)) => tally.notifications += 1,
Ok(Message::Response(_)) => tally.responses += 1,
Err(_) => tally.invalid += 1,
};
match incoming {
Incoming::Single(entry) => count(entry),
Incoming::Batch(entries) => entries.iter().for_each(count),
}
tally
}
fn report<S>(hook: &mut Option<EventFn<S>>, state: &mut S, event: &Event<'_>) {
trace_event(event);
if let Some(hook) = hook {
let _ignored = contain(|| hook(state, event));
}
}