packages feed

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 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