feat(examples): Move echo and net/http examples from `internal/ex…

…amples` to `examples` directory. - Added individual `go.mod` and `go.sum` files for each example. - Added `run.sh` scripts for each example to simplify running the examples. - Added main `README.md` in the examples directory explaining how to get started and run the examples. - API usage was moved to the `USAGE.md` file.
bartventer · Apr 26, 2024 · 5afea8d · 5afea8d
1 parent 3bd4121
commit 5afea8d
Show file tree

Hide file tree

Showing 15 changed files with 499 additions and 178 deletions.
diff --git a/examples/README.md b/examples/README.md
@@ -0,0 +1,44 @@
+# Examples
+
+This directory contains examples of how to use the `gorm-multitenancy` package with different frameworks:
+
+-   [Echo](echo/README.md)
+-   [net/http](nethttp/README.md)
+
+## Getting Started
+
+To run these examples, you have two options:
+
+1. Clone the main repository and navigate to the relevant example directory:
+
+    ```bash
+    go get -u github.com/bartventer/gorm-multitenancy/v5
+    ```
+
+2. Or just clone the relevant example directory directly:
+
+    _Echo example_:
+
+    ```bash
+    go get -u github.com/bartventer/gorm-multitenancy/v5/examples/echo
+    ```
+
+    _net/http example_:
+
+    ```bash
+    go get -u github.com/bartventer/gorm-multitenancy/v5/examples/nethttp
+    ```
+
+## Running the Server
+
+Run the following command from the relevant example directory:
+
+```bash
+./run.sh
+```
+
+This will setup the database and run the server.
+
+## API Usage
+
+Please see [API Usage](USAGE.md) for more examples on how to interact with the server.
diff --git a/examples/USAGE.md b/examples/USAGE.md
@@ -0,0 +1,173 @@
+### API Usage
+
+#### Create tenant
+
+-   Parse the request body into a CreateTenantBody struct
+-   Create the tenant in the database (public schema)
+-   Create the schema for the tenant
+-   Return the HTTP status code 201 and the tenant in the response body
+
+##### Request
+
+```bash
+curl -X POST \
+  http://example.com:8080/tenants \
+  -H 'Content-Type: application/json' \
+  -d '{
+  "domainUrl": "tenant3.example.com"
+}'
+```
+
+##### Response
+
+```json
+{
+    "id": 3,
+    "domainUrl": "tenant3.example.com"
+}
+```
+
+#### Get tenant
+
+-   Get the tenant from the database
+-   Return the HTTP status code 200 and the tenant in the response body
+
+##### Request
+
+```bash
+curl -X GET \
+  http://example.com:8080/tenants/3
+```
+
+##### Response
+
+```json
+{
+    "id": 3,
+    "domainUrl": "tenant3.example.com"
+}
+```
+
+#### Delete tenant
+
+-   Get the tenant from the database
+-   Delete the schema for the tenant
+-   Delete the tenant from the database
+-   Return the HTTP status code 204
+
+##### Request
+
+```bash
+curl -X DELETE \
+  http://example.com:8080/tenants/3
+```
+
+##### Response
+
+```json
+
+```
+
+#### Get books
+
+-   Get the tenant from the request host or header
+-   Get all books for the tenant
+-   Return the HTTP status code 200 and the books in the response body
+
+##### Request
+
+```bash
+curl -X GET \
+  http://example.com:8080/books \
+  -H 'Host: tenant1.example.com'
+```
+
+##### Response
+
+```json
+[
+    {
+        "id": 1,
+        "name": "tenant1 - Book 1"
+    },
+    {
+        "id": 2,
+        "name": "tenant1 - Book 2"
+    }
+]
+```
+
+#### Create book
+
+-   Get the tenant from the request host or header
+-   Parse the request body into a Book struct
+-   Create the book for the tenant in the database
+-   Return the HTTP status code 201 and the book in the response body
+
+##### Request
+
+```bash
+curl -X POST \
+  http://example.com:8080/books \
+  -H 'Content-Type: application/json' \
+  -H 'Host: tenant1.example.com' \
+  -d '{
+  "name": "tenant1 - Book 3"
+}'
+```
+
+##### Response
+
+```json
+{
+    "id": 3,
+    "name": "tenant1 - Book 3"
+}
+```
+
+#### Delete book
+
+-   Get the tenant from the request host or header
+-   Get the book from the database
+-   Delete the book from the database
+-   Return the HTTP status code 204
+
+##### Request
+
+```bash
+curl -X DELETE \
+  http://example.com:8080/books/3 \
+  -H 'Host: tenant1.example.com'
+```
+
+##### Response
+
+```json
+
+```
+
+#### Update book
+
+-   Get the tenant from the request host or header
+-   Get the book from the database
+-   Parse the request body into a UpdateBookBody struct
+-   Update the book in the database
+-   Return the HTTP status code 200
+
+##### Request
+
+```bash
+curl -X PUT \
+  http://example.com:8080/books/2 \
+  -H 'Content-Type: application/json' \
+  -H 'Host: tenant1.example.com' \
+  -d '{
+  "name": "tenant1 - Book 2 - Updated"
+}'
+```
+
+##### Response
+
+```json
+
+```
diff --git a/examples/echo/README.md b/examples/echo/README.md
@@ -0,0 +1,5 @@
+# Echo Example
+
+This is an example of how to use the `gorm-multitenancy` package with the Echo framework.
+
+Please see the [main README.md file](https://github.com/bartventer/gorm-multitenancy/blob/master/examples/README.md) for more information on how to run the server as well as example API usage.
diff --git a/examples/echo/go.mod b/examples/echo/go.mod
@@ -0,0 +1,31 @@
+module github.com/bartventer/gorm-multitenancy/v5/examples/echo
+
+go 1.22.2
+
+require (
+	github.com/bartventer/gorm-multitenancy/v5 v5.9.0
+	github.com/labstack/echo/v4 v4.12.0
+	gorm.io/gorm v1.25.9
+)
+
+require (
+	github.com/golang-jwt/jwt v3.2.2+incompatible // indirect
+	github.com/jackc/pgpassfile v1.0.0 // indirect
+	github.com/jackc/pgservicefile v0.0.0-20231201235250-de7065d80cb9 // indirect
+	github.com/jackc/pgx/v5 v5.5.4 // indirect
+	github.com/jackc/puddle/v2 v2.2.1 // indirect
+	github.com/jinzhu/inflection v1.0.0 // indirect
+	github.com/jinzhu/now v1.1.5 // indirect
+	github.com/labstack/gommon v0.4.2 // indirect
+	github.com/mattn/go-colorable v0.1.13 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/valyala/bytebufferpool v1.0.0 // indirect
+	github.com/valyala/fasttemplate v1.2.2 // indirect
+	golang.org/x/crypto v0.22.0 // indirect
+	golang.org/x/net v0.24.0 // indirect
+	golang.org/x/sync v0.6.0 // indirect
+	golang.org/x/sys v0.19.0 // indirect
+	golang.org/x/text v0.14.0 // indirect
+	golang.org/x/time v0.5.0 // indirect
+	gorm.io/driver/postgres v1.5.7 // indirect
+)
diff --git a/examples/echo/go.sum b/examples/echo/go.sum
@@ -0,0 +1,63 @@
+github.com/bartventer/gorm-multitenancy/v5 v5.9.0 h1:c+BFUFxbL7Uvqo25mJD4SRsU3uU2eDICy2cs5E7azmI=
+github.com/bartventer/gorm-multitenancy/v5 v5.9.0/go.mod h1:FX5LlGCh7AqCWZP155ZKFGXGNlfPvN9pK/TRujtU7cc=
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/golang-jwt/jwt v3.2.2+incompatible h1:IfV12K8xAKAnZqdXVzCZ+TOjboZ2keLg81eXfW3O+oY=
+github.com/golang-jwt/jwt v3.2.2+incompatible/go.mod h1:8pz2t5EyA70fFQQSrl6XZXzqecmYZeUEB8OUGHkxJ+I=
+github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM=
+github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
+github.com/jackc/pgservicefile v0.0.0-20231201235250-de7065d80cb9 h1:L0QtFUgDarD7Fpv9jeVMgy/+Ec0mtnmYuImjTz6dtDA=
+github.com/jackc/pgservicefile v0.0.0-20231201235250-de7065d80cb9/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM=
+github.com/jackc/pgx/v5 v5.5.4 h1:Xp2aQS8uXButQdnCMWNmvx6UysWQQC+u1EoizjguY+8=
+github.com/jackc/pgx/v5 v5.5.4/go.mod h1:ez9gk+OAat140fv9ErkZDYFWmXLfV+++K0uAOiwgm1A=
+github.com/jackc/puddle/v2 v2.2.1 h1:RhxXJtFG022u4ibrCSMSiu5aOq1i77R3OHKNJj77OAk=
+github.com/jackc/puddle/v2 v2.2.1/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
+github.com/jinzhu/inflection v1.0.0 h1:K317FqzuhWc8YvSVlFMCCUb36O/S9MCKRDI7QkRKD/E=
+github.com/jinzhu/inflection v1.0.0/go.mod h1:h+uFLlag+Qp1Va5pdKtLDYj+kHp5pxUVkryuEj+Srlc=
+github.com/jinzhu/now v1.1.5 h1:/o9tlHleP7gOFmsnYNz3RGnqzefHA47wQpKrrdTIwXQ=
+github.com/jinzhu/now v1.1.5/go.mod h1:d3SSVoowX0Lcu0IBviAWJpolVfI5UJVZZ7cO71lE/z8=
+github.com/labstack/echo/v4 v4.12.0 h1:IKpw49IMryVB2p1a4dzwlhP1O2Tf2E0Ir/450lH+kI0=
+github.com/labstack/echo/v4 v4.12.0/go.mod h1:UP9Cr2DJXbOK3Kr9ONYzNowSh7HP0aG0ShAyycHSJvM=
+github.com/labstack/gommon v0.4.2 h1:F8qTUNXgG1+6WQmqoUWnz8WiEU60mXVVw0P4ht1WRA0=
+github.com/labstack/gommon v0.4.2/go.mod h1:QlUFxVM+SNXhDL/Z7YhocGIBYOiwB0mXm1+1bAPHPyU=
+github.com/mattn/go-colorable v0.1.13 h1:fFA4WZxdEF4tXPZVKMLwD8oUnCTTo08duU7wxecdEvA=
+github.com/mattn/go-colorable v0.1.13/go.mod h1:7S9/ev0klgBDR4GtXTXX8a3vIGJpMovkB8vQcUbaXHg=
+github.com/mattn/go-isatty v0.0.16/go.mod h1:kYGgaQfpe5nmfYZH+SKPsOc2e4SrIfOl2e/yFXSvRLM=
+github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
+github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
+github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.9.0 h1:HtqpIVDClZ4nwg75+f6Lvsy/wHu+3BoSGCbBAcpTsTg=
+github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+github.com/valyala/bytebufferpool v1.0.0 h1:GqA5TC/0021Y/b9FG4Oi9Mr3q7XYx6KllzawFIhcdPw=
+github.com/valyala/bytebufferpool v1.0.0/go.mod h1:6bBcMArwyJ5K/AmCkWv1jt77kVWyCJ6HpOuEn7z0Csc=
+github.com/valyala/fasttemplate v1.2.2 h1:lxLXG0uE3Qnshl9QyaK6XJxMXlQZELvChBOCmQD0Loo=
+github.com/valyala/fasttemplate v1.2.2/go.mod h1:KHLXt3tVN2HBp8eijSv/kGJopbvo7S+qRAEEKiv+SiQ=
+golang.org/x/crypto v0.22.0 h1:g1v0xeRhjcugydODzvb3mEM9SQ0HGp9s/nh3COQ/C30=
+golang.org/x/crypto v0.22.0/go.mod h1:vr6Su+7cTlO45qkww3VDJlzDn0ctJvRgYbC2NvXHt+M=
+golang.org/x/net v0.24.0 h1:1PcaxkF854Fu3+lvBIx5SYn9wRlBzzcnHZSiaFFAb0w=
+golang.org/x/net v0.24.0/go.mod h1:2Q7sJY5mzlzWjKtYUEXSlBWCdyaioyXzRB2RtU8KVE8=
+golang.org/x/sync v0.6.0 h1:5BMeUDZ7vkXGfEr1x9B4bRcTH4lpkTkpdh0T/J+qjbQ=
+golang.org/x/sync v0.6.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
+golang.org/x/sys v0.0.0-20220811171246-fbc7d0a398ab/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.19.0 h1:q5f1RH2jigJ1MoAWp2KTp3gm5zAGFUTarQZ5U386+4o=
+golang.org/x/sys v0.19.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ=
+golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
+golang.org/x/time v0.5.0 h1:o7cqy6amK/52YcAKIPlM3a+Fpj35zvRj2TP+e1xFSfk=
+golang.org/x/time v0.5.0/go.mod h1:3BpzKBy/shNhVucY/MWOyx10tF3SFh9QdLuxbVysPQM=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gorm.io/driver/postgres v1.5.7 h1:8ptbNJTDbEmhdr62uReG5BGkdQyeasu/FZHxI0IMGnM=
+gorm.io/driver/postgres v1.5.7/go.mod h1:3e019WlBaYI5o5LIdNV+LyxCMNtLOQETBXL2h4chKpA=
+gorm.io/gorm v1.25.9 h1:wct0gxZIELDk8+ZqF/MVnHLkA1rvYlBWUMv2EdsK1g8=
+gorm.io/gorm v1.25.9/go.mod h1:hbnx/Oo0ChWMn1BIhpy1oYozzpM15i4YPuHDmfYtwg8=
diff --git a/internal/examples/echo/main.go → examples/echo/main.go b/internal/examples/echo/main.go → examples/echo/main.go
diff --git a/examples/echo/run.sh b/examples/echo/run.sh
@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+
+# Starts local Postgres instance for the example and runs the example.
+
+set -euo pipefail
+
+# Database configuration
+DB_HOST=localhost
+DB_PORT=5432
+DB_USER=tenants
+DB_NAME=tenants
+DB_PASSWORD=tenants
+
+module_name=$(grep -oP 'module \K(.*)' go.mod)
+last_part=$(basename "$module_name")
+container_name="postgres-$last_part"
+
+# Find an unused port
+while lsof -Pi :$DB_PORT -sTCP:LISTEN -t >/dev/null; do
+    DB_PORT=$((DB_PORT + 1))
+done
+
+echo ":: Starting local Postgres instance for the $last_part example..."
+echo -e "\t- Database: $DB_NAME"
+echo -e "\t- User: $DB_USER"
+echo -e "\t- Password: $DB_PASSWORD"
+echo -e "\t- Host: $DB_HOST"
+echo -e "\t- Port: $DB_PORT"
+docker rm -f "$container_name" &>/dev/null || :
+docker run -d --name "$container_name" \
+    -e POSTGRES_DB="$DB_NAME" \
+    -e POSTGRES_USER="$DB_USER" \
+    -e POSTGRES_PASSWORD="$DB_PASSWORD" \
+    -p "$DB_PORT":5432 \
+    postgres:"15.4-alpine" &>/dev/null
+
+echo "OK. Run \"docker rm -f $container_name\" to clean up the container."
+echo
+
+sleep 10
+
+echo ":: Running the $last_part example..."
+DB_HOST=$DB_HOST DB_PORT=$DB_PORT DB_USER=$DB_USER DB_NAME=$DB_NAME DB_PASSWORD=$DB_PASSWORD go run . "$@"
diff --git a/examples/nethttp/README.md b/examples/nethttp/README.md
@@ -0,0 +1,5 @@
+# net/http Example
+
+This is an example of how to use the `gorm-multitenancy` package with the net/http package.
+
+Please see the [main README.md file](https://github.com/bartventer/gorm-multitenancy/blob/master/examples/README.md) for more information on how to run the server as well as example API usage.
diff --git a/examples/nethttp/go.mod b/examples/nethttp/go.mod
@@ -0,0 +1,22 @@
+module github.com/bartventer/gorm-multitenancy/v5/examples/nethttp
+
+go 1.22.2
+
+require (
+	github.com/bartventer/gorm-multitenancy/v5 v5.9.0
+	gorm.io/gorm v1.25.9
+)
+
+require (
+	github.com/jackc/pgpassfile v1.0.0 // indirect
+	github.com/jackc/pgservicefile v0.0.0-20231201235250-de7065d80cb9 // indirect
+	github.com/jackc/pgx/v5 v5.5.4 // indirect
+	github.com/jackc/puddle/v2 v2.2.1 // indirect
+	github.com/jinzhu/inflection v1.0.0 // indirect
+	github.com/jinzhu/now v1.1.5 // indirect
+	github.com/urfave/negroni v1.0.0
+	golang.org/x/crypto v0.22.0 // indirect
+	golang.org/x/sync v0.6.0 // indirect
+	golang.org/x/text v0.14.0 // indirect
+	gorm.io/driver/postgres v1.5.7 // indirect
+)