blob: 1edf67a4a216041c11add922aaf024e57bbe011a [file]
/-
Copyright (c) 2021 Microsoft Corporation. All rights reserved.
Released under Apache 2.0 license as described in the file LICENSE.
Authors: Wojciech Nawrocki
-/
import Lean.Data.Json
/-! Allows LSP clients to make Remote Procedure Calls to the server.
The single use case for these is to allow the infoview UI to refer to and manipulate heavy-weight
objects residing on the server. It would be inefficient to serialize these into JSON and send over.
For example, the client can format an `Expr` without transporting the whole `Environment`.
All RPC requests are relative to an open file and an RPC session for that file. The client must
first connect to the session using `$/lean/rpc/connect`. -/
namespace Lean.Lsp
/-- An object which RPC clients can refer to without marshalling. -/
structure RpcRef where
/- NOTE(WN): It is important for this to be a single-field structure
in order to deserialize as an `Object` on the JS side. -/
p : USize
deriving BEq, Hashable, FromJson, ToJson
instance : ToString RpcRef where
toString r := toString r.p
end Lean.Lsp
namespace Lean.Server
structure RpcObjectStore : Type where
/-- Objects that are being kept alive for the RPC client, together with their type names,
mapped to by their RPC reference.
Note that we may currently have multiple references to the same object. It is only disposed
of once all of those are gone. This simplifies the client a bit as it can drop every reference
received separately. -/
aliveRefs : PersistentHashMap Lsp.RpcRef Dynamic := {}
/-- Value to use for the next `RpcRef`. It is monotonically increasing to avoid any possible
bugs resulting from its reuse. -/
nextRef : USize := 0
def rpcStoreRef (any : Dynamic) : StateM RpcObjectStore Lsp.RpcRef := do
let st ← get
set { st with
aliveRefs := st.aliveRefs.insert ⟨st.nextRef⟩ any
nextRef := st.nextRef + 1
}
return ⟨st.nextRef⟩
def rpcGetRef (r : Lsp.RpcRef) : ReaderT RpcObjectStore Id (Option Dynamic) :=
return (← read).aliveRefs.find? r
def rpcReleaseRef (r : Lsp.RpcRef) : StateM RpcObjectStore Bool := do
let st ← get
if st.aliveRefs.contains r then
set { st with aliveRefs := st.aliveRefs.erase r }
return true
else
return false
/-- `RpcEncodable α` means that `α` can be deserialized from and serialized into JSON
for the purpose of receiving arguments to and sending return values from
Remote Procedure Calls (RPCs).
Any type with `FromJson` and `ToJson` instances is `RpcEncodable`.
Furthermore, types that do not have these instances may still be `RpcEncodable`.
Use `deriving RpcEncodable` to automatically derive instances for such types.
This occurs when `α` contains data that should not or cannot be serialized:
for instance, heavy objects such as `Lean.Environment`, or closures.
For such data, we use the `WithRpcRef` marker.
Note that for `WithRpcRef α` to be `RpcEncodable`,
`α` must have a `TypeName` instance
On the server side, `WithRpcRef α` is just a structure
containing a value of type `α`.
On the client side, it is an opaque reference of (structural) type `Lsp.RpcRef`.
Thus, `WithRpcRef α` is cheap to transmit over the network
but may only be accessed on the server side.
In practice, it is used by the client to pass data
between various RPC methods provided by the server. -/
-- TODO(WN): for Lean.js, compile `WithRpcRef` to "opaque reference" on the client
class RpcEncodable (α : Type) where
rpcEncode : α → StateM RpcObjectStore Json
rpcDecode : Json → ExceptT String (ReaderT RpcObjectStore Id) α
export RpcEncodable (rpcEncode rpcDecode)
instance : Nonempty (RpcEncodable α) :=
⟨{ rpcEncode := default, rpcDecode := default }⟩
instance [FromJson α] [ToJson α] : RpcEncodable α where
rpcEncode a := return toJson a
rpcDecode j := ofExcept (fromJson? j)
instance [RpcEncodable α] : RpcEncodable (Option α) where
rpcEncode v := toJson <$> v.mapM rpcEncode
rpcDecode j := do Option.mapM rpcDecode (← fromJson? j)
-- TODO(WN): instance [RpcEncodable α β] [Traversable t] : RpcEncodable (t α) (t β)
instance [RpcEncodable α] : RpcEncodable (Array α) where
rpcEncode a := toJson <$> a.mapM rpcEncode
rpcDecode b := do Array.mapM rpcDecode (← fromJson? b)
instance [RpcEncodable α] [RpcEncodable β] : RpcEncodable (α × β) where
rpcEncode := fun (a, b) => return toJson (← rpcEncode a, ← rpcEncode b)
rpcDecode j := do
let (a, b) ← fromJson? j
return (← rpcDecode a, ← rpcDecode b)
instance [RpcEncodable α] : RpcEncodable (StateM RpcObjectStore α) where
rpcEncode fn := fn >>= rpcEncode
rpcDecode j := do
let a : α ← rpcDecode j
return return a
/-- Marks values to be encoded as opaque references in RPC packets.
See the docstring for `RpcEncodable`. -/
structure WithRpcRef (α : Type u) where
val : α
deriving Inhabited
instance [TypeName α] : RpcEncodable (WithRpcRef α) :=
{ rpcEncode, rpcDecode }
where
-- separate definitions to prevent inlining
rpcEncode r := toJson <$> rpcStoreRef (.mk r.val)
rpcDecode j := do
let r ← fromJson? j
match (← rpcGetRef r) with
| none => throw s!"RPC reference '{r}' is not valid"
| some any =>
if let some obj := any.get? α then
return ⟨obj⟩
else
throw s!"RPC call type mismatch in reference '{r}'\nexpected '{TypeName.typeName α}', got '{any.typeName}'"
end Lean.Server