368 lines
20 KiB
Markdown
368 lines
20 KiB
Markdown
# Hyper PyFleX
|
|
|
|
Thx to https://hypermedia.systems/ for the book.
|
|
Really nice.
|
|
|
|
## Me
|
|
No web dev before
|
|
Like coding, AI, casual geek
|
|
Was a full python dev, never really touched anything else
|
|
Wanted to do SaaS, like software
|
|
Didn't do CS, did Thermal and Energy Engineering
|
|
First wanted to become data scientist then engineer then software dev then full stack dev. Guess I want to do everything so full stack make sense
|
|
|
|
## Intro
|
|
Don't wanted to learn JS so search and found HTMX, was a revelation. I couldn't understand why everybody use JS client if this is available. I mean to do for some highly performant software. But I use python as a backend so, yeah. I have the phylosiphie of simplicity. SOmething simple is something durable, reparaible, upgradable, understadable, ect.
|
|
|
|
Call me crazy but I don't comment my code, or few. I do more docs than comments. Why ? Because my code need to be my comment. I need to be able to understand what this code do by looking at it. Simplicity is readable, understable. So I can upgrade it or repaire it, ect. I guess because I didn't do a CS degree, I don't have strong beleive in comment or stuff said at school.
|
|
|
|
So when I saw some JS code and started to do some basic stuff using chatGPT to give me a script that add a row to a table. I made it work, my app was pretty good, not a lot JS. But WHAT A PAIN IN THE ASS. And look at this shit! How ugly it is. I can't read it. I mean I know, I need to learn JS, code, blablabla to understand it like I understand python, blablabla. I KNOW, I don't WANT to lear JS. Ear me out, I am not saying that JS is bad at all, I'm sure it's great, but I don't WANT to know, I want to stick with what I know, my beloved python and my easy pandas, numpy and stuff. Web dev suck rn because of that in my opinion, you need to learn JS, and not small Java, did you see the size of Java client for some basic stuff ? Crazy !!! JS is the popular because you are force to use this shit. Anyway, no djugi here right ?
|
|
|
|
Anyway, I did the first version of my app using streamlit. Streamlit, if you don't know, it's great, it's easy, it's python. I know, I know, I'm biais, bite me. I did a really great app with it, I wouln't be ashame to share it as if and try to sell it. Specially if I needed to learn JS lol, no way, prefer stick to streamlit than learning JS. That's why thx god HTMX. So for this first version, I used mongoDB as a DB, and I like it. I first took it for the vector seach, that I used it in the v1! But removed to focus on the chat, but I had a all library, import doc, semantic search and shit. And I was already a bit using the idea of HTMX in some way.
|
|
|
|
All data was in mongoDB, and nothing store locally, everytime I reload the script I get the data from mongo and display the messages. Some peoples would tell me "but that useless and you use databse cpu, you should add the message to the db and update a list of message in your client app and then trigger an event on just the chat to blablabla" Well no, I'm not doing that. I keep it simple. And it was the best idea. At first I was worry "it's stupid, it will broke so fast". But guess what, quite the oposite. In fact it was so easy to add features !!! For example I want to add a message to the conversation, well I add it to the db and reload the script, that's it. So I can do it from anywere, at anytime, whithout breaking anything. Noting in the style of "but this small thing need to be change because of this special scenario because I am in this part of the app and not here, blablabla" Nothing, Easy. Yes I end up doing client -> server -> db -> server -> client
|
|
|
|
So HTMX feeled a bit similare. Instead of Client + Server, it is Server + Screen. No client, that is the core idea of Hyper PyFleX. Easy, no JS, no client/server shit.
|
|
And the beauty is that Hyper PyFleX is obviously all about HTMX. So you can do like Hyper GinX for Go + Gin + HTMX or Hyper RailX, ect
|
|
The Hyper in all of them is for Hypermedia in HTML, whick is the heart of how internet and webbrowser work and mostly display and organise things. (Recommand https://hypermedia.systems/) TODO ADD the acrynyme from the books
|
|
Another huhg advantages of using HTMX instead of JS is that you can use all HTML library, like alpine.js, ect.
|
|
|
|
The core idea being that the server send all the browser need to know t odisplay the app. It doesn't need to understand what the app is or do, all of that is either in the HTML, in our head or in the server.
|
|
When I click on a button to remove something, the client don't understand that I want to remove something. It just understand that I want to change this part. And if the change happend to be an empty HTML, well it's been "removed".
|
|
Compare to the API phylosophy where the server send just the data, but then the server need a function that understand and interpret the data.
|
|
|
|
For example I want to display a username and an email. If my API send this:
|
|
```html
|
|
<h1>Adrien</h1>
|
|
<p>adrien.bouvais@blabla.com<p>
|
|
```
|
|
In this response, there is everything the browser need to know to display. The name is an header and above the mail, ect. I can update, put the email next to the name, ect.
|
|
|
|
Now let's see the current approche. Usuqlly server send JSON to the client and then the client need to do stuff.
|
|
```json
|
|
{
|
|
"name" : "Adrien",
|
|
"email" : "adrien.bouvais@blabla.com"
|
|
}
|
|
```
|
|
|
|
But with that, you don't know how to display it. You need a new JS function to pass from one to another.
|
|
|
|
Why ? I already did the logic server side of getting the data, ect. Why do I need to split some part in JS and do some shit twice ?
|
|
|
|
## part 0 - table
|
|
|
|
At my work, I was task to implement an app. The app is pretty simple. You have a table that is a list of test done on a database. You can see the number of errors. For each test there is a button to see the detail.
|
|
|
|
To understand here a test example: I have a list of client, I check if any have more than 5 addresses. If so, when I click on the +, I get a new table that list all client with more than 5 addresses. And there is multiple test like that.
|
|
Pretty simple right ? Well no, obviously.
|
|
|
|
Man, I stuggeled so hard to just add one + button for the details. And then if I do that, it change that, and that and blablabla and it lag and it's not center. God damm, that why I don't wanted JS, I don't know JS. I did a script to exclude a row of the second table and it would react... What a mistake, I think I touched the ultimate use case here, how easy it is in HTMX compare to the other way is just incridible.
|
|
And now the ultimate roast for JS. Yes JS on client side is in theory more efficient... in theory. But I don't know what I'm am doing here! chatGPT gave me this and it work but god, I use it for python and sometime it give me somecrazy shit. Just to say that it is if you know what you are doing. Way better to stick to the language you know, here you can do someting opti, here you understand.
|
|
|
|
Let's go into a bit of code. So I have my Flask app running (I use Flask for my work)
|
|
```python
|
|
from flask import Flask, render_template, request
|
|
|
|
app = Flask(__name__)
|
|
|
|
@app.route('/')
|
|
def index():
|
|
return render_template('demo1.html')
|
|
|
|
if __name__ == '__main__':
|
|
app.run(debug=True)
|
|
```
|
|
|
|
That look like that:
|
|
TODO Add image demo1
|
|
|
|
Easy enough. A list and a form with 2 input and a button.
|
|
|
|
Obviously I want to do 2 things, be able to add row and delete it. With JS, a bit of a pain in the ass. I know that some people will come with "just import react and react a React component then link it to the react hook to auto react to action of the user react blablabla". But let's ee how HTMX would to it. First the table itself:
|
|
```html
|
|
<table>
|
|
<thead>
|
|
<tr>
|
|
<th></th>
|
|
<th>Name</th>
|
|
<th>Age</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
<tr>
|
|
<td><button>Delete</button></td>
|
|
<td>John</td>
|
|
<td>20</td>
|
|
</tr>
|
|
<tr>
|
|
<td><button>Delete</button></td>
|
|
<td>Jane</td>
|
|
<td>21</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
```
|
|
|
|
So a table with a header, 2 columns and then a body and 2 rows. Now I want the button to remove the row.
|
|
First I will add it `hx-get="/demo1/delete"`. It mean *if the button is click, run this and use what it return*. What it return is ALWAYS an HTML.
|
|
Then `hx-swap="outerHTML"` it mean *replace the old HTML with the new one*.
|
|
And to finish `hx-target="closest tr"` it mean *do the change on this*. In this case the closest tr is the parent parent of the button, or the row the button is currently in.
|
|
With all change, we got:
|
|
```html
|
|
<table class="table">
|
|
<thead>
|
|
<tr>
|
|
<th></th>
|
|
<th>Name</th>
|
|
<th>Age</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody id="table_body">
|
|
<tr>
|
|
<td><button hx-target="closest tr" hx-get="/demo1/delete" hx-swap="outerHTML">Delete</button></td>
|
|
<td>John</td>
|
|
<td>20</td>
|
|
</tr>
|
|
<tr>
|
|
<td><button hx-target="closest tr" hx-get="/demo1/delete" hx-swap="outerHTML">Delete</button></td>
|
|
<td>Jane</td>
|
|
<td>21</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
```
|
|
|
|
No we just need to implement the route `/demo1/delete`. Well easy, it is supose to return the new HTML of a delete row... Meaning nothing, the funtion need to return nothing.
|
|
```python
|
|
@app.route('/demo1/delete', methods=['GET'])
|
|
def demo1_delete():
|
|
return ''
|
|
```
|
|
|
|
That's it! Ofc, at this point, you should do some server stuff. Meaning update the database ect. I don't do that here, I just show the interactivity, so if I reload the page, all changes are lost.
|
|
|
|
ANd the button work, if I click I instently remove it. It REACT! It's ALIVE and JSless!
|
|
Surely the form to add data isn't that simple...
|
|
```html
|
|
<form hx-post="/demo1/add" hx-target="#table_body" hx-swap="beforeend">
|
|
<input class="input" type="text" placeholder="Name" name="name" />
|
|
<input class="input" type="text" placeholder="Age" name="age" />
|
|
<input class="button is-primary" type="submit" value="Submit" />
|
|
</form>
|
|
```
|
|
|
|
Yes, that's it. If I click on Submit, I instantly get a new row!
|
|
|
|
Let's see what it do. So like before `hx-post` will issue a request to the server, a POST this time.
|
|
`hx-swap="beforeend"` mean *appends the content after the last child inside the target*. So after the last row of the table (can also be `afterbegin` to append at the beginning of the table)
|
|
`hx-target="#table_body"` is the `tbody` of the table above.
|
|
Let's see `/demo1/add`:
|
|
```python
|
|
@app.route('/demo1/add', methods=['POST'])
|
|
def demo1():
|
|
name = request.form['name']
|
|
age = request.form['age']
|
|
if name and age:
|
|
return f"<tr><td><button class='button is-danger is-small' hx-target='closest tr' hx-get='/demo1/delete' hx-swap='outerHTML'>Delete</button></td><td>{name}</td><td>{age}</td></tr>"
|
|
return ''
|
|
```
|
|
|
|
The function return the HTML of a new row. ANd because I say to add it after the last child of the `tbody`, it add a row to the table.
|
|
|
|
And that's it for this first demo/intro. We were able to do some crazy stuff in very few line. I highly recommand reading the HTMX doc in the future to check all availables features.
|
|
|
|
I was able to learn and do the app it few days while doing other stuff and managing issue on the dev virtual machine.
|
|
The shit was really impressive, and my boss is really similare to me in the way he don"t want to learn JS. He was really impressed.
|
|
|
|
So after that, I was convinced. Let's do JADE 2.0 using HTMX.
|
|
|
|
## Why GO ?
|
|
|
|
After doing a really simple chat where I can write and it answer in like 1-2h. I realease my python code is simple asf.
|
|
I also realise how I want my app to work and it's simple. remember simplicity boys!!!
|
|
|
|
So how it work. Every time I do something in the chat. I recreate it.
|
|
Let's take an example, I want to add a message to the chat:
|
|
User trigger and send form with message content --> Server get form content and add a message to the database --> Run main generateChatHTML (Read DB -> Generate HTML) -> Send to the client to update just the chat
|
|
|
|
The goal is once again simplicity. All data are at one place, the database, where it bellow. If I need it, I read the database. There is no buffer, no global messages array that keep track of mesages in GO, and not at all in both in GO and in JS on the client. Then I need to be sure that they are identical, too much trubble, why would I do that ?
|
|
Idk how stupid it is to use this for big app in prod, but worse case you can do a compose and add a mongodb buffer and only receive once and save once when leaving.
|
|
|
|
So here a simple diagramm to understand:
|
|
|
|
|
|
|
|
Compare to the more traditional approche:
|
|
|
|
|
|
|
|
Or even worse, with JS
|
|
|
|
|
|
|
|
Yep, this is how I see it. WTF is wrong with you peoples? 3 loops ????? 3???? I meqn 2 OOOKKK, I guesssssssss. But 3????
|
|
So If I want to update something in my app, I first need to process the data in JS and updatte what need to be in the JS client then send only the necessarry data through an API in a specific format and have a specific function that receive this specific data and do some stuff on the server, change some stuff and then send the data to the database. Ok we update one thing!
|
|
Don't get me wrong, I see the point of using JS. This is not a loop, the data never comeback from the databse to the client! The server never send anything. Meaning it never do the server to client part that HTMX do. So you do transfert more data for similare optimization level for the same thing but, is it better optimizing that if I get a 500mb RAM client ? Depend the app, no in a lot of scenario I beleive.
|
|
|
|
Note that in the first one, there is 2 data box. Meaning 2 "states of data". This is the key difference. In the second one, the server is responsible for keeping track of the data as it stay inside it and just send the necessary data to the databse. It is efficient, that is for sure, but the server AND the databse need to keep track of the same thing, that is redondant.
|
|
|
|
So after chossing to go with this design, as it is basically the same logic I use in streamlit with st.rerun(). I needed a server efficient, powerful and fast !!!
|
|
|
|
*Process to look at python code*
|
|
|
|
Yeah.....
|
|
I like you python ,that is for sure. But maybe I need someone else on this job. So I alredy had some eyes on GO and was looking for a good project to use it. I saw other framework and language like Rust, ect. I was thinking about mojo at some point, but it is not mature enough at this point. But could of been a good use case for it.
|
|
|
|
So GO it is, I did the good old google "Go web framwork" and found a good list, tested with Gin then went with Fiber for the SPEEDDDDDDDDDDDDDDDDDDDDDDDDD!!!!!!!!! YOOOOOOOOOOOLLLLLLLOOOOOOOO!!!!!!!!
|
|
|
|
No seriously, had to chose, looked really similare. Tryed Fiber and found it easy to use and powerful so went with it.
|
|
|
|
## Used teck
|
|
So here my full teck stack
|
|
- GO with Fiber
|
|
- HTMX
|
|
- MongoDB
|
|
- Bulma
|
|
|
|
Done
|
|
|
|
## part 1 - The chat
|
|
|
|
Ok so as a first thing is a chat. What I need is:
|
|
- Text input at the bottom of the screen
|
|
- Avatar and message bubble
|
|
|
|
Should be easy right ? Hopefully with HTMX yes. Let's try...
|
|
|
|
Well it do was pretty easy. I first did a base.html and then added an navbar and a page.html a bit like that:
|
|
```html
|
|
{% extends 'base.html' %}
|
|
|
|
{% block content %}
|
|
<div class="columns" style="width: 100%;">
|
|
<div class="column" id="messages" hx-get="/chat/messages" hx-trigger="load" hx-swap="outerHTML">
|
|
</div>
|
|
</div>
|
|
|
|
<form hx-post="/chat" hx-target="#messages" hx-swap="outerHTML">
|
|
<input class="input" type="text" placeholder="Type your message here..." name="message" />
|
|
</form>
|
|
|
|
<style>
|
|
.column {
|
|
display: flex;
|
|
flex-direction: column;
|
|
}
|
|
|
|
.message {
|
|
max-width: 90%;
|
|
margin-bottom: 10px;
|
|
}
|
|
|
|
.message-user {
|
|
align-self: flex-start;
|
|
}
|
|
|
|
.message-bot {
|
|
align-self: flex-end;
|
|
}
|
|
</style>
|
|
|
|
{% endblock %}
|
|
```
|
|
|
|
So in this HTML, I have a columns with one column empty for now and a form with an input. I also created a small style so the text are on the right or left of the colum depending of if user of bot and that's it.
|
|
|
|
Now in this HTML, I use HTMX at 2 places, the column and the form. Let's take a look at the column first:
|
|
- `hx-trigger="load"` mean *when the page load*
|
|
- `hx-get="/chat/messages"` *get the HTML here*
|
|
- `hx-swap="outerHTML"` *to replace yourself with the response*
|
|
|
|
The HTML at /chat/messages look like:
|
|
```html
|
|
<div class="column" id="messages">
|
|
{% for message in messages %}
|
|
{% if message.Role == 'user' %}
|
|
<article class="message message-user" id='{{ message.id }}'>
|
|
<div class="message-header">
|
|
<p>User</p>
|
|
<form hx-delete="/chat" hx-swap="outerHTML" hx-target="#messages">
|
|
<input type="hidden" name="messageId" value='{{ message.id }}'>
|
|
<button class="delete" aria-label="delete"></button>
|
|
</form>
|
|
</div>
|
|
<div class="message-body">
|
|
{{ message.Content }}
|
|
</div>
|
|
</article>
|
|
{% else %}
|
|
<article class="message message-bot" id='{{ message.id }}'>
|
|
<div class="message-header">
|
|
<p>Bot</p>
|
|
<form hx-delete="/chat" hx-swap="outerHTML" hx-target="#messages">
|
|
<input type="hidden" name="messageId" value='{{ message.id }}'>
|
|
<button class="delete" aria-label="delete"></button>
|
|
</form>
|
|
</div>
|
|
<div class="message-body">
|
|
{{ message.Content }}
|
|
</div>
|
|
</article>
|
|
{% endif %}
|
|
{% endfor %}
|
|
</div>
|
|
```
|
|
|
|
So it create itself back with `<div class="column" id="messages">` and then do a for loop on the messages that I extracted from the Database on the server side.
|
|
|
|
Now let's take a look at the `form`:
|
|
- `hx-posts="/chat"` mean *get the HTML here*
|
|
- `hx-swap="outerHTML"` *to replace*
|
|
- `hx-target="#messages"` *this with the response*
|
|
|
|
The server function at POST /chat will add the message in the databse then return the same as /chat/messages. So if you understand, the function at /chat/messages is the second "Server" box on my diagram. And it's always the same function. Once again simplicity. Out of 4 boxs, only one change basically, the first "Server". Meaning the function that change the database.
|
|
|
|
And yeah, that's it. A bit of backend but just this:
|
|
```go
|
|
func addMessageHandler(c *fiber.Ctx) error {
|
|
message := c.FormValue("message")
|
|
|
|
collection := mongoClient.Database("chat").Collection("messages")
|
|
collection.InsertOne(context.Background(), bson.M{"message": message, "role": "user", "date": time.Now()})
|
|
collection.InsertOne(context.Background(), bson.M{"message": "I did something!", "role": "bot", "date": time.Now()})
|
|
|
|
return generateChatHTML(c)
|
|
}
|
|
|
|
func generateChatHTML(c *fiber.Ctx) error {
|
|
collection := mongoClient.Database("chat").Collection("messages")
|
|
|
|
// Get all messages
|
|
cursor, _ := collection.Find(context.TODO(), bson.D{})
|
|
|
|
// Convert the cursor to an array of messages
|
|
var messages []Message
|
|
if err = cursor.All(context.TODO(), &messages); err != nil {
|
|
return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{
|
|
"error": "Failed to convert cursor to array",
|
|
})
|
|
}
|
|
|
|
// Render the HTML template with the messages
|
|
return c.Render("chat/messages", fiber.Map{
|
|
"messages": messages,
|
|
})
|
|
}
|
|
```
|
|
|
|
And that' it! The chat work like that! Obviously I need to add the model api stuff with it but otherwise... done. I just did an ineractive chat in what ? 100 lines of codes ? And in an easy to understand, share and maintain way ? Isn't it beautifull?
|
|
|
|
## part 2 - The API
|
|
|
|
Ok so now that we have a chat. I need to be able to communicate with the different API. I'm a bit affray on this one, I hope I don't NEED to use python. Now that I think about, I always used the OpenAI Client, because easy to use. Let's see if I can talk with OpeanAI server through Go first...
|
|
|
|
|
|
|
|
# Conclusion
|
|
- Say a lot about JS during the article. JS is great, I guess, I didn't try. Every language have strenght weakness, blablabla. The point is that it shouln't be a necessity to learn it. And it shouldn't be so difficult to do basic stuff. |