Refractoring proposal about speckle-sharp HOT 2 CLOSED

maybe it's just me, maybe it's some of the git lingo

This can be the start of a beautiful song 🎶 I totally agree there's some naming problems that cause confusion. Relying on git lingo was a partially conscious choice, on the lines of "if you're a developer working with core programatically, you hopefully use a VCS, and grok some of the terminology". Regardless, I'm happy to revisit that choice, as I feel as well it's not the best, and, as demonstrated, potentially causes confusion.

Based on your input, I'll try and unpack some of it to move the discussion forward. Important preamble: the current api in core is the "low level" one, and most of these DX problems can be solved by exposing "higher level", friendlier routes down the line (which we'll figure out while developing connectors; which is what you've started doing, and I guess, these questions arise).

Transports

Transports can be local or remote, and ultimately they're agnostic if you write to/read from the local hard drive, a local db, a remote db, or the server, or a different server. The main difference is how they're used, especially when reading in the deserialisation process (to a lesser extent it's similarly important in the writing process during serialisation). One way they are used is synchronous, and the other way is asynchronous.

So rather than renaming ITransport to IRemote, I'd just differentiate to ITransportSync and ITransportAsync. This will also solve the confusion you pointed out below:

rename ITransport to IRemote. I find it confusing that we have both transports and remotes and that Remote is a type of transport and that we also have a class named Remote

The Remote is definitively not a type a transport! Which brings us to:

Remotes

rename Remote.cs to SpeckleServer

Down with that.

Upload/Download

rename Upload to Send and Download to Receive (sorry did't think about this before)

You actually did 😄 The history of the names of these functions is (a) Push/Pull at the beginning, then based on your input (b) Send/Receive, then I changed them to (c) Upload/Download after a bit. The last name change, from (b) to (c) happened because I felt that sending something is, in speckle lingo, tied to an actual stream (ie, I'm sending to a stream, same for receiving: I'm receiving from a stream).

In 2.0, what these two functions actually do is send objects to (or receive from) one or more remotes rather than an actual stream/commit. Important note here: one still needs to tag a "commit" (this is going to be another long naming discussion based on @izzylys latest user test) on an object hash from what has just been sent.

In my mind, the jury's out on this one. I feel like renaming them might cause other confusion down the line ("Q: but i just sent to speckle, why does it not show up in my stream; A: you need to create a commit afterwards") and will not necessarily solve it.

Perhaps adding (1) Send method that does upload + commit creation in one go and (2) Receive method that takes a commit's id on the Remote/SpeckleServer class would be better?

Move methods Upload/Download (Send/Receive) to IRemote

We've discussed this previously, and it's a nope. The static Upload/Send method can take one or more transports, and uploads objects to all of them in parallel - this is the most efficient way. For clarity and simplicity, we can definitively add to the Remote/SpeckleServer class an Upload method that just sends to one transport, namely the async one associated with that server.

from speckle-sharp.

After a voice dicussion it was decided:

• keep ITransport and various transports named the same
• rename Remote.cs to Client.cs as it's an actual Speckle client, calling the Speckle API
• rename Upload to Send and Download to Receive
• remove the StreamId property from Remote.cs/Client.cs

from speckle-sharp.