Conversation
| - Telefunc makes it easy to add RPC to your server, but it's up to you to take advantage of the benefits RPC has to offer. | ||
| - Improve performance. | ||
| - Improve application security. | ||
| - Telefunc is easy to add RPC to your server — you can use Telefunc in parallel to your server. It's up to you how much RPC you want to use (you can progressively migrate back and forth between your server API endpoints and Telefunc). It's up to you to take advantage of the benefits RPC has to offer. |
There was a problem hiding this comment.
agreed that there needs to be more emphasis on how easy it is to migrate to/from telefunc, but
- the final bullet was meant to emphasize that RPC is pattern moreso than a technology. i.e., you can use telefunc in a way that bypasses the potential performance benefits
- i think this is an important point to make clearly early-on; let me know if you have thoughts on how to better express that
- the migration DX is a point i would emphasize later in the docs. i agree that it makes sense to mention early-on, but i'd think of it more as a detail than a vertical of its own, e.g.,
- Allow for rapid and flexible iteration.
+ - Easy to progressively add (or remove) from project
- Improve application security.
- It's up to you to take advantage of the benefits RPC has to offer.
There was a problem hiding this comment.
i wanted to expand on this a bit
i'd think of it more as a detail than a vertical of its own
as i understand it, RPC's main value prop is the design pattern, which allows for
- better dx (i.e., faster iteration)
- related code is close together
- development is full-stack
- no schemas to build or maintain
- easy to add, remove, migrate progressively
- minimal/tailored request payloads
- better security
- better performance
in my mind, these are two main values, from which all the rest follow. in the introduction, i think it's helpful to
- focus on the high-level rather than the detail
- group related values/ideas to help readers build the right mental model
There was a problem hiding this comment.
👍 It all makes sense.
i think this is an important point to make clearly early-on; let me know if you have thoughts on how to better express that
Nice idea 😍 How about:
Telefunc is a tool, as well as a new mental model we call
*Event-based telefunctions* for maximum development speed.Btw. I'd suggest we avoid the term "RPC" outside the /RPC and /RPC-vs-GraphQL-REST pages. Most users don't know what RPC means. If the user doesn't want to learn then it's better we don't confront him with the term "RPC".
| - RPC is a pattern for calling a remote function as if it were colocated with the client. No adapters or injection needed. | ||
| 1. Create named Telefunctions to call the database or do other backend work. | ||
| - RPC is a pattern for calling a remote function as if it were define in the client. Zero boilerplate. | ||
| 1. Create telefunctions (on the server) to call the database or do other backend work. |
There was a problem hiding this comment.
nit: the parenthetical feels a little redundant. the context of this list is "a pattern for calling a remote fn", so to me it's clear that telefunctions are remote.
if i'm wrong about the clarity, i'd suggest that's a more general issue, and that the outline needs to do a better job of explaining the control flow early-on.
- parentheticals can add helpful context, but can also be distracting/interrupt reading. a strong foundation of knowledge/context, is often enough.
but it could also be helpful to add a simple flow diagram.
sequenceDiagram
Client->>Server: Request
Server-->>Telefunction: Telefunction args
Telefunction--)Server: Telefunction return
Server->>Client: Response
There was a problem hiding this comment.
👍 Good point. I can see that I'm often too conservative in my writing (repeating myself too much).
So far I think we don't need a diagram (for this). Although it could be nice to use diagrams for things that are hard to communicate succinctly. E.g. for the RPC vs REST/GraphQL page, a diagram could be very helpful. Or maybe https://telefunc.com/event-based could also benefit a diagram — not sure how the diagram would look like, but that could be very powerful. The mental model is quite important (a lot more important than the RPC vs REST/GraphQL page).
| ::: info | ||
| - The term RPC is often used loosely to denote RPC-like approaches, like creating JSON endpoints. | ||
| - RPC-like describes an API that is schemaless — in contrast to RESTful and GraphQL APIs that always have a schema. | ||
| - RPC-like describes an API that is schemaless — in contrast to RESTful and GraphQL APIs which have a schema. |
There was a problem hiding this comment.
nit: i'm actually not sure which is correct.
"that" vs "which" is a confusing english rule. as i understand it, it basically depends on whether the clause you're adding is required or supplemental
"The cat, which is hungry, ran away from home"
- knowing that the cat is hungry is bonus info -> which
"The scratch that the cat gave me stings"
- knowing which scratch you're talking about is required -> that
the guide i use is basically "which" if i use a comma, otherwise "that", but it's imperfect.
this case seems like a gray area to me, but i would lean towards "that", because "have a schema" is clarifying info, rather than definitional. either works though
There was a problem hiding this comment.
👍 Didn't know that.
My main motivation was to remove always. Because many users say they're building a REST API, but what they're actually doing is creating JSON enpoints without following any kinds of schemas. Many(/most?) users don't know that REST => RESTful level-3 => schema. Instead of teaching users about REST, we can accept the confusion and mostly talk about generic APIs (GraphQL/REST) in the comparison page. Event though users might not follow the level-3 schema thing, I think most are still building an API that is somewhat generic (few endpoints to cover a max number of use cases). So I'd frame the discussion around "event-based" VS "generic".
| ## Securing resources | ||
| - Always keep in mind that your **telefuncs are public**. | ||
| - A simple HTTP request could be used to extract, modify, or destroy user secrets or business-critical data from an unprotected function. | ||
| - Always keep in mind that your **telefunctions are public**. |
There was a problem hiding this comment.
it might be good to more prominently introduce/define the term "telefunction" earlier in the docs
| - Don't forget to sanitize SQL arguments | ||
| - Allows argument types to be inferred. | ||
| - Telefunc generates a `shield` automatically from TypeScript types, if available. | ||
| - Telefunc generates a `shield` automatically from TypeScript types. |
There was a problem hiding this comment.
what was your motivation here? if i understand the docs correctly, a shield is only generated if you use typescript/add types to your telefunctions.
There was a problem hiding this comment.
Yes, shield() is only auto generated for TypeScript telefunctions. I was just making it slightly more succinct (kinda what you said above: "with a strong foundation we can be more succinct"). We probably agree here.
| - The naming convention enforces coupling, which is a cornerstone of keeping RPC calls lithe (i.e., avoiding function scope creep). | ||
| - The naming convention enforces coupling, which is a cornerstone of keeping RPC calls slim (i.e., avoiding function scope creep). | ||
| - Opting out of the naming convention is perfectly fine, though we recommend having a clear reason for doing so. | ||
| > @ambergristle I didn't know the word "lithe" — I guess many non-native English speakers won't know it either |
There was a problem hiding this comment.
good call-out!
i studied literature for years, and still talk like an english professor sometimes. 😆 usually i catch stuff like that in review, but i appreciate the reminder to keep a global audience in mind!
| > @ambergristle I didn't know the word "lithe" — I guess many non-native English speakers won't know it either | ||
|
|
||
| - Accordingly, RPC versioning is typically equivalent to project versioning. You will need a custom solution if you choose to use RPC with a monorepo. | ||
| > @ambergristle The best pattern here is to always deploy the frontend and JS server at the same time. Versioning telefunctions are a pain (even more than versionin RESTFul/GraphQL APIs because telefunctions change a *lot* more change generic RESTful/GraphQL APIs) — it's a core Telefunc philosophy: you develop frontend hand-in-hand with telefunctions. The backend can be decoupled using a three party setup: static files (frontend) + JS server for SSR + telefunctions (frontend) + backend (Java/Ruby/...) — this setup is commonly called "BFF" (backend-for-frontend). |
There was a problem hiding this comment.
thanks for the added detail! this was one of the weaker sections, and some of the detail about monorepos/project structure got lost in the shuffle.
- Telefunc is most effective when used with a monorepo architecture, allowing close coupling and dynamic type-sharing between frontend and backend.
- Telefunctions can change as fast as your UI, so deploying frontend and backend at the same time radically simplifies versioning.
it's a core Telefunc philosophy: you develop frontend hand-in-hand with telefunctions
i tried to emphasize this in the outline, but i think there's opportunity for improvement. it's a really important point to make, but also quite difficult to communicate. i'm still trying to figure out what helped me shift my mental model/understand it.
There was a problem hiding this comment.
I think the best is to have a single repository that holds both the frontend and telefunctions. No monorepo.
2 participants
@ambergristle Feel free to push back as much as you want. While I know this is just a plan, I nit-picked here and there for the sake of exchanging style preferences — happy to discover your style preferences as well (I really like what I'm seeing and curious to discover more).