{"action":"closed","issue":{"url":"https://api.github.com/repos/yarpc/yarpc-go/issues/251","repository_url":"https://api.github.com/repos/yarpc/yarpc-go","labels_url":"https://api.github.com/repos/yarpc/yarpc-go/issues/251/labels{/name}","comments_url":"https://api.github.com/repos/yarpc/yarpc-go/issues/251/comments","events_url":"https://api.github.com/repos/yarpc/yarpc-go/issues/251/events","html_url":"https://github.com/yarpc/yarpc-go/issues/251","id":164622598,"number":251,"title":"Rename top-level RPC object to RPC Plane","user":{"login":"breerly","id":263587,"avatar_url":"https://avatars.githubusercontent.com/u/263587?v=3","gravatar_id":"","url":"https://api.github.com/users/breerly","html_url":"https://github.com/breerly","followers_url":"https://api.github.com/users/breerly/followers","following_url":"https://api.github.com/users/breerly/following{/other_user}","gists_url":"https://api.github.com/users/breerly/gists{/gist_id}","starred_url":"https://api.github.com/users/breerly/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/breerly/subscriptions","organizations_url":"https://api.github.com/users/breerly/orgs","repos_url":"https://api.github.com/users/breerly/repos","events_url":"https://api.github.com/users/breerly/events{/privacy}","received_events_url":"https://api.github.com/users/breerly/received_events","type":"User","site_admin":false},"labels":[],"state":"closed","locked":false,"assignee":null,"assignees":[],"milestone":{"url":"https://api.github.com/repos/yarpc/yarpc-go/milestones/1","html_url":"https://github.com/yarpc/yarpc-go/milestones/Finalize%20API","labels_url":"https://api.github.com/repos/yarpc/yarpc-go/milestones/1/labels","id":1813972,"number":1,"title":"Finalize API","description":null,"creator":{"login":"breerly","id":263587,"avatar_url":"https://avatars.githubusercontent.com/u/263587?v=3","gravatar_id":"","url":"https://api.github.com/users/breerly","html_url":"https://github.com/breerly","followers_url":"https://api.github.com/users/breerly/followers","following_url":"https://api.github.com/users/breerly/following{/other_user}","gists_url":"https://api.github.com/users/breerly/gists{/gist_id}","starred_url":"https://api.github.com/users/breerly/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/breerly/subscriptions","organizations_url":"https://api.github.com/users/breerly/orgs","repos_url":"https://api.github.com/users/breerly/repos","events_url":"https://api.github.com/users/breerly/events{/privacy}","received_events_url":"https://api.github.com/users/breerly/received_events","type":"User","site_admin":false},"open_issues":6,"closed_issues":10,"state":"open","created_at":"2016-06-07T17:30:24Z","updated_at":"2016-07-13T17:56:54Z","due_on":null,"closed_at":null},"comments":13,"created_at":"2016-07-08T21:46:39Z","updated_at":"2016-07-13T17:56:54Z","closed_at":"2016-07-13T17:56:54Z","body":"## The Problem\r\n\r\n@bombela, being new to YARPC, brought up a really good naming smell when he was trying to understand all the objects at play and their responsibilities - \r\n\r\n> It took me awhile to get that the top-level RPC object was actually the YARPC context, that contained all the config needed to register procedures, create clients, and send/receive messages. I always think of an individual message when I hear RPC.\r\n\r\nAnd he's not wrong, when people hear \"RPC\" they think about it used in the common context:\r\n\r\n> In my application, I send RPCs to the users service on a 5 minute interval.\r\n\r\nWithin our group even, we've taken to calling it the **Top-level RPC Object** to disambiguate. \r\n\r\nI think we can do much better; calling it the **Top-level RPC Object** is a mouthful, and it isn't super obvious what that means. It's come to mean something for our team, but FX proved that the term will be confusing for newcomers to the system (and I agree).\r\n\r\nI suggest we rename this term to something that:\r\n\r\n- Is not yet used or overloaded\r\n- Is immediately obvious \r\n- Fits the responsibility of the object better\r\n\r\n## The Proposal\r\n\r\nI'd like that name be **RPC Plane**. \r\n\r\nLook how this term brings clarity to the object model:\r\n\r\n> The RPC Plane is the object used to configure your YARPC application; it hands RPCs to your Procedures, and it is used by Encoding Clients to send RPCs. The RPC Plane is what allows your application to be **Transport-agnostic**.\r\n\r\nNow lets switch the term back to **top-level RPC** object:\r\n\r\n> The Top-level RPC object is the object used to configure your YARPC application; it hands RPCs to your Procedures, and it is used by Encoding Clients to send RPCs. The Top-level RPC object is what allows your application to be **Transport-agnostic**.\r\n\r\nNot nearly as clear. \r\n\r\n## In Practice\r\n\r\nHow will the RPC Plane affect clarity of code? Positively, I think:\r\n\r\n```go\r\n// First, create an RPC Plane. This object contains all the info\r\n// necessary to send and receive RPCs.\r\nplane := yarpc.NewPlane(\"myservice\", ...)\r\n\r\n// Next, register some Procedures. As RPCs come across \r\n// the RPC Plane, they are handed to your Procedures for processing\r\njson.Register(plane, json.Procedure(\"hello\", hello))\r\n\r\n// Inversely, Encoding Clients use the RPC Plane to send RPCs\r\nusers := json.New(plane.Channel(\"users\"))\r\n\r\n// Finally, start the RPC Plane. This allows all the Plane's internals to initiate, \r\n// and creates space to \"warmup\" before RPCs start flying. Just think of starting \r\n// the RPC Plane like takeoff - no RPCs can be sent or received before this point.\r\nplane.Start()\r\n```\r\n\r\nNote that the RPC Plane should never leave the `main`, instead, an app should be structured like so:\r\n\r\n1. Configure an RPC Plane in `main` (either by hand or with help from YAML)\r\n2. Create Encoding Clients for every service you wish to talk to\r\n3. Register Procedures and Handlers\r\n4. Inject Encoding Clients into the parts of your application that needs them.\r\n\r\n---\r\n\r\nI'm open to different terms, but I do want to get away from this:\r\n\r\n```go\r\nrpc := yarpc.New(\"myservice\", ...)\r\n```\r\n\r\nThoughts? "}}
{"actor":{"display_login":"breerly"}}