plexus-protocol 0.7.0.0 → 0.8.0.0
raw patch · 5 files changed
+214/−5 lines, 5 filesPVP ok
version bump matches the API change (PVP)
API changes (from Hackage documentation)
+ Plexus.Schema.Recursive: MethodRolePeer :: Maybe Text -> Maybe Text -> Maybe PeerInterface -> MethodRole
+ Plexus.Schema.Recursive: PeerInterface :: Text -> Text -> Value -> Map Text Text -> PluginSchema -> PeerInterface
+ Plexus.Schema.Recursive: [childSchema] :: MethodRole -> Maybe PluginSchema
+ Plexus.Schema.Recursive: [interfaceHash] :: PeerInterface -> Text
+ Plexus.Schema.Recursive: [interfaceIr] :: PeerInterface -> Value
+ Plexus.Schema.Recursive: [interfaceMethods] :: PeerInterface -> Map Text Text
+ Plexus.Schema.Recursive: [interfaceName] :: PeerInterface -> Text
+ Plexus.Schema.Recursive: [interfaceSchema] :: PeerInterface -> PluginSchema
+ Plexus.Schema.Recursive: [peerInterface] :: MethodRole -> Maybe PeerInterface
+ Plexus.Schema.Recursive: data PeerInterface
+ Plexus.Schema.Recursive: instance Data.Aeson.Types.FromJSON.FromJSON Plexus.Schema.Recursive.PeerInterface
+ Plexus.Schema.Recursive: instance Data.Aeson.Types.ToJSON.ToJSON Plexus.Schema.Recursive.PeerInterface
+ Plexus.Schema.Recursive: instance GHC.Classes.Eq Plexus.Schema.Recursive.PeerInterface
+ Plexus.Schema.Recursive: instance GHC.Generics.Generic Plexus.Schema.Recursive.PeerInterface
+ Plexus.Schema.Recursive: instance GHC.Show.Show Plexus.Schema.Recursive.PeerInterface
+ Plexus.Schema.Recursive: isSlotRole :: MethodRole -> Bool
+ Plexus.Transport: fetchSchemaAtIfAny :: SubstrateConfig -> [Text] -> IO (Either TransportError (Maybe PluginSchema))
+ Plexus.Transport: schemaNotFound :: [PlexusStreamItem] -> Bool
- Plexus.Schema.Recursive: MethodRoleDynamicChild :: Maybe Text -> Maybe Text -> MethodRole
+ Plexus.Schema.Recursive: MethodRoleDynamicChild :: Maybe Text -> Maybe Text -> Maybe PluginSchema -> MethodRole
Files
- CHANGELOG.md +28/−0
- plexus-protocol.cabal +1/−1
- src/Plexus/Schema/Recursive.hs +77/−3
- src/Plexus/Transport.hs +35/−1
- test/Main.hs +73/−0
CHANGELOG.md view
@@ -1,5 +1,33 @@ # Changelog for plexus-protocol +## 0.8.0.0++A schema's slots as plexus-core 0.10 writes them (NEST-5, NEST-7;+SYNAPSE-41). Breaking: `MethodRole` gains a constructor and a field, so an+exhaustive match or a positional pattern on it changes.++### Breaking++- **`MethodRolePeer { listMethod, searchMethod, peerInterface }`**: a peer+ slot (`#[plexus_macros::peer]`, e.g. plexus-dyn's `dyn.peer.<name>`). On the+ wire it is plexus-core's `{"kind": "static_child", "peer": true, …}` — read+ as `MethodRolePeer` and written back the same; a `static_child` without+ `peer` (or with `peer: false`) is `MethodRoleStaticChild` as before.+- **`MethodRoleDynamicChild` gains `childSchema :: Maybe PluginSchema`**: a+ typed dynamic child's slot type (`child`). `MethodRoleDynamicChild lm sm`+ is now `MethodRoleDynamicChild lm sm ch`.++### Added++- `PeerInterface` (`name`, `hash`, `ir` kept as JSON, `methods`, `schema`):+ plexus-core's `peer::Interface`. A slot type or interface this reader+ cannot read leaves the slot untyped rather than failing the schema.+- `isSlotRole`: a dynamic child or a peer slot — a role whose names are open.+- `Plexus.Transport.fetchSchemaAtIfAny`: the schema at a path that may not be+ there — `Right Nothing` when the service says activation or method not+ found (or a slot's `not_found`), every other failure `Left` as `fetchSchemaAt` says it;+ `schemaNotFound` is its test on a call's items.+ ## 0.7.0.0 bidir removed (ASK-1, ASK-3). Breaking.
plexus-protocol.cabal view
@@ -1,6 +1,6 @@ cabal-version: 3.0 name: plexus-protocol-version: 0.7.0.0+version: 0.8.0.0 synopsis: Plexus RPC protocol types and client description: Haskell types and a client for Plexus RPC, a streaming JSON-RPC 2.0 protocol: stream items and provenance, recursive plugin and method
src/Plexus/Schema/Recursive.hs view
@@ -39,6 +39,8 @@ , DeprecationInfo(..) , ParamSchema(..) , MethodRole(..)+ , PeerInterface(..)+ , isSlotRole -- * The caller's view (AUTH-3 / AUTH-4) , View(..)@@ -115,9 +117,14 @@ -- @ -- {"kind": "rpc"} -- {"kind": "static_child"}--- {"kind": "dynamic_child", "list_method": "planet_names", "search_method": null}+-- {"kind": "static_child", "peer": true, "list_method": "names", "interface": {…}}+-- {"kind": "dynamic_child", "list_method": "planet_names", "search_method": null, "child": {…}} -- @ --+-- A peer slot (NEST-7, @#[plexus_macros::peer]@) goes on the wire as a+-- @static_child@ marked @peer: true@, as plexus-core's @MethodRoleWire@+-- writes it; it is read as 'MethodRolePeer' and written back the same.+-- -- Defaults to 'MethodRoleRpc' when absent so pre-IR servers deserialize -- cleanly (see 'MethodSchema.methodRole' parser). data MethodRole@@ -126,27 +133,94 @@ | MethodRoleDynamicChild { listMethod :: Maybe Text , searchMethod :: Maybe Text+ , childSchema :: Maybe PluginSchema+ -- ^ NEST-5: the slot's type, for a typed dynamic child (@child@) }+ | MethodRolePeer+ -- ^ NEST-7: a slot of peers found by name at call time: the segment+ -- after the method is a peer's name (@dyn.peer.<name>.…@)+ { listMethod :: Maybe Text+ , searchMethod :: Maybe Text+ , peerInterface :: Maybe PeerInterface+ -- ^ a typed peer slot's interface (@interface@)+ } deriving stock (Show, Eq, Generic) +-- | NEST-7: a peer's shape, named and content-addressed — plexus-core's+-- @peer::Interface@: its name, the shape's hash, its IR (kept as the+-- JSON it came as), each method's own hash, and the schema it was read+-- from.+data PeerInterface = PeerInterface+ { interfaceName :: Text+ , interfaceHash :: Text+ , interfaceIr :: Value+ , interfaceMethods :: Map Text Text+ , interfaceSchema :: PluginSchema+ }+ deriving stock (Show, Eq, Generic)++instance FromJSON PeerInterface where+ parseJSON = withObject "PeerInterface" $ \o -> PeerInterface+ <$> o .: "name"+ <*> o .: "hash"+ <*> o .:? "ir" .!= Null+ <*> o .:? "methods" .!= mempty+ <*> o .: "schema"++instance ToJSON PeerInterface where+ toJSON PeerInterface{..} = object+ [ "name" .= interfaceName+ , "hash" .= interfaceHash+ , "ir" .= interfaceIr+ , "methods" .= interfaceMethods+ , "schema" .= interfaceSchema+ ]++-- | Whether a role is a slot whose names are open: a dynamic child's keys+-- or a peer slot's peers (NEST-5, NEST-7).+isSlotRole :: MethodRole -> Bool+isSlotRole = \case+ MethodRoleDynamicChild{} -> True+ MethodRolePeer{} -> True+ _ -> False+ instance FromJSON MethodRole where parseJSON = withObject "MethodRole" $ \o -> do kind <- o .: "kind" :: Parser Text case kind of "rpc" -> pure MethodRoleRpc- "static_child" -> pure MethodRoleStaticChild+ "static_child" -> do+ peer <- o .:? "peer" .!= False+ if peer+ then MethodRolePeer+ <$> o .:? "list_method"+ <*> o .:? "search_method"+ -- an interface this reader cannot read leaves the slot untyped+ <*> (o .:? "interface" <|> pure Nothing)+ else pure MethodRoleStaticChild "dynamic_child" -> MethodRoleDynamicChild <$> o .:? "list_method" <*> o .:? "search_method"+ -- a slot type this reader cannot read leaves the slot untyped+ <*> (o .:? "child" <|> pure Nothing) other -> fail $ "Unknown MethodRole kind: " <> T.unpack other +-- | Encodes as plexus-core's @MethodRoleWire@: an absent optional field is+-- omitted, and a peer slot is a @static_child@ with @peer: true@. instance ToJSON MethodRole where toJSON MethodRoleRpc = object ["kind" .= ("rpc" :: Text)] toJSON MethodRoleStaticChild = object ["kind" .= ("static_child" :: Text)]- toJSON (MethodRoleDynamicChild lm sm) =+ toJSON (MethodRoleDynamicChild lm sm ch) = object $ ("kind" .= ("dynamic_child" :: Text)) : catMaybes [ ("list_method" .=) <$> lm , ("search_method" .=) <$> sm+ , ("child" .=) <$> ch+ ]+ toJSON (MethodRolePeer lm sm iface) =+ object $ ("kind" .= ("static_child" :: Text)) : ("peer" .= True) : catMaybes+ [ ("list_method" .=) <$> lm+ , ("search_method" .=) <$> sm+ , ("interface" .=) <$> iface ] -- | Shallow parameter schema with optional per-field deprecation.
src/Plexus/Transport.hs view
@@ -16,6 +16,8 @@ -- * Schema Fetching , fetchSchemaAt+ , fetchSchemaAtIfAny+ , schemaNotFound , fetchMethodSchemaAt , extractSchema , extractSchemaResult@@ -47,7 +49,7 @@ import Plexus.Client (SubstrateConfig(..), LostConnection(..), connect, disconnect, substrateRpc, substrateRpcDuplex, defaultConfig) import Plexus.Input (InputHalf) import Plexus.Client.Pool (ConnectionPool, createConnectionPool, withPooledConnection, defaultPlexusPoolConfig)-import Plexus.RemoteError (renderRemoteError)+import Plexus.RemoteError (RemoteError(..), renderRemoteError) import Plexus.Types (PlexusStreamItem(..), TransportError(..)) import Plexus.Schema.Recursive (PluginSchema, MethodSchema, SchemaResult(..), parsePluginSchema, parseSchemaResult) @@ -235,6 +237,38 @@ Right items -> case extractSchema items of Left parseErr -> pure $ Left $ ProtocolError parseErr -- Parse errors are protocol errors Right schema -> pure $ Right schema++-- | NEST-5 / NEST-7: the schema at a path that may not be there — a name+-- in a slot (a dynamic child's key, a peer's name). @Right Nothing@ when+-- the service says there is nothing at the path (activation or method not+-- found, as a call failure or a JSON-RPC @-32601@; a slot's own+-- @not_found@, as plexus-core's @PeerError::NotFound@); every other failure+-- (the connection, a refusal, an unreadable answer) is @Left@, as+-- 'fetchSchemaAt' says it.+fetchSchemaAtIfAny :: SubstrateConfig -> [Text] -> IO (Either TransportError (Maybe PluginSchema))+fetchSchemaAtIfAny cfg path = do+ let backend = substrateBackend cfg+ let schemaMethod = if null path+ then backend <> ".schema"+ else T.intercalate "." path <> ".schema"+ result <- rpcCallWith cfg (backend <> ".call") (object ["method" .= schemaMethod])+ pure $ case result of+ Left transportErr -> Left transportErr+ Right items+ | schemaNotFound items -> Right Nothing+ | otherwise -> either (Left . ProtocolError) (Right . Just) (extractSchema items)++-- | Whether a schema call's items say there is nothing at its path: no+-- schema, and the first failure is activation or method not found, or+-- a slot's @not_found@.+schemaNotFound :: [PlexusStreamItem] -> Bool+schemaNotFound items =+ null [() | StreamData _ _ ct _ <- items, ".schema" `T.isSuffixOf` ct]+ && case [err | StreamError _ _ err _ <- items] of+ (ActivationNotFound _ : _) -> True+ (MethodNotFound _ _ : _) -> True+ (Other "not_found" _ : _) -> True+ _ -> False -- | Extract PluginSchema from stream items -- Returns Either Text for application-level errors (not transport)
test/Main.hs view
@@ -36,6 +36,7 @@ import Plexus.RemoteError import Plexus.Schema.Recursive import Plexus.Types hiding (GuidanceErrorType (..))+import Plexus.Transport (schemaNotFound) -- ============================================================================ -- The fixture@@ -165,6 +166,7 @@ strictnessSpec mergedSpec noBidirSpec+ slotSpec schemaSpec :: Spec schemaSpec = describe "expected/schema.json" $ do@@ -762,3 +764,74 @@ case item of StreamData _ _ _ c -> c `shouldBe` content other -> expectationFailure ("not a data item: " <> show other)++-- | NEST-5 / NEST-7 (SYNAPSE-41): a schema's slots as plexus-core 0.10+-- writes them — a peer slot is a @static_child@ marked @peer@, with its+-- list and search methods and its interface; a dynamic child carries its+-- slot type as @child@. Each reads and writes back the same; a schema from+-- before them reads as it did.+slotSpec :: Spec+slotSpec = describe "slots: peer and typed dynamic child (NEST-5, NEST-7)" $ do+ let schema ns = object+ [ "namespace" .= s ns, "version" .= s "0.1.0", "description" .= s "d", "hash" .= s "h1"+ , "methods" .= [ object [ "name" .= s "get", "description" .= s "g", "hash" .= s "m1"+ , "returns" .= object [], "cardinality" .= s "one"+ , "http_method" .= s "POST", "role" .= object ["kind" .= s "rpc"] ] ] ]+ iface = object+ [ "name" .= s "forge", "hash" .= s "ih", "ir" .= object ["irVersion" .= s "3.0"]+ , "methods" .= object ["get" .= s "m1"], "schema" .= schema "forge" ]++ it "a peer slot reads as MethodRolePeer and writes back as static_child with peer" $ do+ let v = object [ "kind" .= s "static_child", "peer" .= True, "list_method" .= s "names"+ , "search_method" .= s "find", "interface" .= iface ]+ r <- roundTrips @MethodRole id v+ case r of+ MethodRolePeer (Just "names") (Just "find") (Just i) -> do+ interfaceName i `shouldBe` "forge"+ psNamespace (interfaceSchema i) `shouldBe` "forge"+ other -> expectationFailure ("not a typed peer slot: " <> show other)+ isSlotRole r `shouldBe` True++ it "an untyped peer slot (dyn.peer) reads with its list method alone" $ do+ r <- roundTrips @MethodRole id (object ["kind" .= s "static_child", "peer" .= True, "list_method" .= s "names"])+ r `shouldBe` MethodRolePeer (Just "names") Nothing Nothing++ it "a static child without peer, or with peer false, is the nullary static child" $ do+ decodes (object ["kind" .= s "static_child"]) `shouldBe` Right MethodRoleStaticChild+ decodes (object ["kind" .= s "static_child", "peer" .= False]) `shouldBe` Right MethodRoleStaticChild+ isSlotRole MethodRoleStaticChild `shouldBe` False++ it "a typed dynamic child keeps its slot type" $ do+ let v = object [ "kind" .= s "dynamic_child", "list_method" .= s "names", "child" .= schema "config_key" ]+ r <- roundTrips @MethodRole id v+ fmap psNamespace (childSchema r) `shouldBe` Just "config_key"+ isSlotRole r `shouldBe` True++ it "an untyped dynamic child (before NEST-5) reads as before" $ do+ r <- roundTrips @MethodRole id (object ["kind" .= s "dynamic_child", "list_method" .= s "planet_names"])+ r `shouldBe` MethodRoleDynamicChild (Just "planet_names") Nothing Nothing++ it "a slot type or interface this reader cannot read leaves the slot untyped" $ do+ decodes (object ["kind" .= s "dynamic_child", "child" .= s "?"])+ `shouldBe` Right (MethodRoleDynamicChild Nothing Nothing Nothing)+ decodes (object ["kind" .= s "static_child", "peer" .= True, "interface" .= object ["name" .= s "x"]])+ `shouldBe` Right (MethodRolePeer Nothing Nothing Nothing)++ it "a method whose role is a peer slot round-trips through MethodSchema" $ do+ let m = object+ [ "name" .= s "peer", "description" .= s "a peer", "hash" .= s "p1"+ , "returns" .= object [], "cardinality" .= s "one", "http_method" .= s "POST"+ , "role" .= object ["kind" .= s "static_child", "peer" .= True, "list_method" .= s "names"] ]+ ms <- roundTrips @MethodSchema id m+ methodRole ms `shouldBe` MethodRolePeer (Just "names") Nothing Nothing++ it "a schema call's items say not found only for activation or method not found" $ do+ let meta = Provenance ["svc"]+ err e = StreamError "" meta e False+ schemaNotFound [err (ActivationNotFound "nope")] `shouldBe` True+ schemaNotFound [err (MethodNotFound "dyn" "nope")] `shouldBe` True+ schemaNotFound [err (Other "not_found" KM.empty)] `shouldBe` True+ schemaNotFound [err (Other "forbidden_peer" KM.empty)] `shouldBe` False+ schemaNotFound [err Unauthenticated] `shouldBe` False+ schemaNotFound [err (Execution "boom")] `shouldBe` False+ schemaNotFound [] `shouldBe` False