From e6ca6efe233c398622e4557adbda7cdf64807e82 Mon Sep 17 00:00:00 2001 From: David Schmitt Date: Thu, 21 Mar 2019 15:25:19 +0000 Subject: [PATCH 1/3] Add reserved and recommended keywords for transport schemas --- language/resource-api/README.md | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/language/resource-api/README.md b/language/resource-api/README.md index 28d1363..0358e3c 100644 --- a/language/resource-api/README.md +++ b/language/resource-api/README.md @@ -370,7 +370,7 @@ To support Puppet versions prior to 6, see the [Legacy Support](#legacy-support) ### Transport ```ruby -# lib/puppet/transport/nexus_schema.rb +# lib/puppet/transport/schema/nexus.rb Puppet::ResourceAPI.register_transport( name: 'nexus', # points at class Puppet::Transport::Nexus desc: 'Connects to a Cisco Nexus device', @@ -418,6 +418,26 @@ A transport connects providers to the remote target. It consists of the schema a Password attributes should also set `sensitive: true` to ensure that the data is handled securely. Attributes marked with this flag allow any UI based off this schema to make appropriate presentation choices. The value will be passed to the transport wrapped in a `Puppet::Pops::Types::PSensitiveType::Sensitive`. This will keep the value from being logged or saved inadvertently while it is being transmitted between components. To access the value within the Transport use the `unwrap` method. e.g. `connection_info[:password].unwrap`. +The following keywords are encouraged within the transport schema: + +* `uri` - Use when you need to specify a specific URL to connect to. All of the following keys will be computed from the `uri` if possible. In the future more url parts may be computed from the URI as well. +* `host` - Use to specify and IP or address to connect to. +* `protocol` - Use to specify which protocol the transport should use for example `http`, `https`, `ssh` or `tcp` +* `user` - The user the transport should connect as. +* `port` - The port the transport should connect to. + +The following keywords must not be used by the transport schema: + +* `name` - transports should use `uri` instead of name. +* `path` - reserved as a uri part +* `query` - reserved as a uri part +* `run-on` - This is used by bolt to determine which target to proxy to. Transports should not rely on this key. +* `remote-transport` - This is used to determine which transport to load. It should always be the transport class name "declassified". +* `remote-*` Any key starting with `remote-` is reserved for future use. +* `implementations`: reserved by boltThere are some reserved keywords that cannot be used as connection info attributes: + + + The transport implementation must implement the following methods: * `initialize(context, connection_info)` From 22f5f34c186b97c470948279ae68380f9f8250d6 Mon Sep 17 00:00:00 2001 From: David Schmitt Date: Thu, 21 Mar 2019 17:16:49 +0000 Subject: [PATCH 2/3] Remove copy&paste mistake --- language/resource-api/README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/language/resource-api/README.md b/language/resource-api/README.md index 0358e3c..4bdc5ba 100644 --- a/language/resource-api/README.md +++ b/language/resource-api/README.md @@ -434,9 +434,7 @@ The following keywords must not be used by the transport schema: * `run-on` - This is used by bolt to determine which target to proxy to. Transports should not rely on this key. * `remote-transport` - This is used to determine which transport to load. It should always be the transport class name "declassified". * `remote-*` Any key starting with `remote-` is reserved for future use. -* `implementations`: reserved by boltThere are some reserved keywords that cannot be used as connection info attributes: - - +* `implementations`: reserved by bolt The transport implementation must implement the following methods: From df914aa7fdba773a55053560bd772db14fa4e290 Mon Sep 17 00:00:00 2001 From: clairecadman Date: Mon, 25 Mar 2019 08:12:08 +0000 Subject: [PATCH 3/3] Update README.md This commit makes minor edits. --- language/resource-api/README.md | 34 ++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/language/resource-api/README.md b/language/resource-api/README.md index 4bdc5ba..d5898e2 100644 --- a/language/resource-api/README.md +++ b/language/resource-api/README.md @@ -418,23 +418,23 @@ A transport connects providers to the remote target. It consists of the schema a Password attributes should also set `sensitive: true` to ensure that the data is handled securely. Attributes marked with this flag allow any UI based off this schema to make appropriate presentation choices. The value will be passed to the transport wrapped in a `Puppet::Pops::Types::PSensitiveType::Sensitive`. This will keep the value from being logged or saved inadvertently while it is being transmitted between components. To access the value within the Transport use the `unwrap` method. e.g. `connection_info[:password].unwrap`. -The following keywords are encouraged within the transport schema: - -* `uri` - Use when you need to specify a specific URL to connect to. All of the following keys will be computed from the `uri` if possible. In the future more url parts may be computed from the URI as well. -* `host` - Use to specify and IP or address to connect to. -* `protocol` - Use to specify which protocol the transport should use for example `http`, `https`, `ssh` or `tcp` -* `user` - The user the transport should connect as. -* `port` - The port the transport should connect to. - -The following keywords must not be used by the transport schema: - -* `name` - transports should use `uri` instead of name. -* `path` - reserved as a uri part -* `query` - reserved as a uri part -* `run-on` - This is used by bolt to determine which target to proxy to. Transports should not rely on this key. -* `remote-transport` - This is used to determine which transport to load. It should always be the transport class name "declassified". -* `remote-*` Any key starting with `remote-` is reserved for future use. -* `implementations`: reserved by bolt +A transport schema accepts the following keywords: + +* `uri`: use when you need to specify a specific URL to connect to. All of the following keys will be computed from the `uri` when possible. In the future more url parts may be computed from the URI. +* `host`: use to specify an IP or address to connect to. +* `protocol`: use to specify which protocol the transport should use for example `http`, `https`, `ssh` or `tcp`. +* `user`: the user the transport should connect as. +* `port`: the port the transport should connect to. + +Do not use the following keywords when writing a schema: + +* `name`: transports should use `uri` instead of name. +* `path`: reserved as a uri part. +* `query`: reserved as a uri part. +* `run-on`: This is used by Bolt to determine which target to proxy to. Transports should not rely on this key. +* `remote-transport`: This is used to determine which transport to load. It should always be the transport class named "declassified". +* `remote-*`: any key starting with `remote-` is reserved for future use. +* `implementations`: reserved by Bolt. The transport implementation must implement the following methods: