https://github.com/amirhnajafiz/ghoster
A Golang server-less application example.
https://github.com/amirhnajafiz/ghoster
function-as-a-service go golang serverless
Last synced: 15 days ago
JSON representation
A Golang server-less application example.
- Host: GitHub
- URL: https://github.com/amirhnajafiz/ghoster
- Owner: amirhnajafiz
- Created: 2021-12-13T16:51:57.000Z (almost 4 years ago)
- Default Branch: master
- Last Pushed: 2024-04-23T16:03:29.000Z (over 1 year ago)
- Last Synced: 2025-06-23T04:41:22.066Z (4 months ago)
- Topics: function-as-a-service, go, golang, serverless
- Language: Go
- Homepage:
- Size: 388 KB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# :ghost: Ghoster
In this project, I implemented a simple server-less application for executing Golang functions. Ghoster is a **FaaS**(Function as a Service) application. As the name suggests, it executes Golang functions on demand. Ghoster is a minimal version of server-less applications like AWS lambda. My purpose in creating this application is to take a deep dive into server-less systems. At this moment, Ghoster can handle simple Golang projects. It cannot handle complex applications like web/HTTP servers, etc.
The way it works is like a layered system. It contains an HTTP server in order to handle user requests, a metrics server to export Ghoster Prometheus metrics, a file server for managing functions/projects, and an exec component for handling FaaS requests.
## Run Ghoster using Docker
In order to execute Ghoster, you need to set some environment variables, mount the functions directory (it will be used by file server and exec component in order to do the FaaS logic), and build the application docker image.
### env variables
As you can see in the below table, in order to configure a Ghoster, you have to set the following environmental variables.
| Name | Description | Type | Example value |
| ---------------------- | ------------------------------------- | ---- |---------------|
| ```HTTP_PORT``` | Ghoster gateway port | integer | 8080 |
| ```FILE_SERVER_PORT``` | File server port | integer | 8081 |
| ```METRICS_PORT``` | Metrics exporter port | integer | 8082 |
| ```METRICS_NS``` | Metrics namespace | string | default |
| ```METRICS_SS``` | Metrics subsystem | string | ghoster |
| ```POOL_SIZE``` | Number of Ghoster concurrent workers | integer | 10 |
| ```GC_INTERVAL``` | Garbage collector interval in seconds | integer | 120 |
### functions dir mount
Ghoster stores Golang projects in a directory called ```functions```. The file server write new functions in this directory, and the exec component loads each function from this directory. Therefore, make sure to mount this directory.
Each project needs to have a ```main.go```, ```go.mod```, and ```README.md```. The readme file will be the description of each function. A suggested project structure is like this:
```
|_ internal/
|_ pkg/
|_ main.go
|_ go.mod
|_ go.sum
|_ README.md
```
When you want to upload a new function, make sure to use file server and upload your project as a ```.zip``` format.
### docker command
In order to build and run Ghoster using docker, you can use the two following commands:
```sh
docker pull ghcr.io/amirhnajafiz/ghoster:latest
docker run -d -it -e HTTP_PORT=8080 -p 8080:8080 -v $(pwd)/functions:/var/ghoster/functions ghcr.io/amirhnajafiz/ghoster:latest
```
## Interface
Ghoster uses **HTTP** requests for registring projects, listing projects, and executing them. In this section we are going to give you some examples in ```curl``` in order to work with Ghoster.
### upload a new function
```sh
curl -i -X POST \
-F "file_name=subtraction" \
-F "file=@Archive.zip" \
localhost:8001/files
```
### list functions
```sh
curl -i -X GET localhost:8080/functions
```
### get function description
```sh
curl -i -X GET localhost:8080/functions/{function-name}
```
### execute a function
```sh
curl -i -X POST -H 'Content-type: application/json' -d '{"args": ["10", "2"]}' localhost:8080/functions/{function-name}
```
Input params are in ```JSON``` format. The ```args``` field is an array of input arguments to the function.
## Metrics
Ghoster Prometheus metrics are exported in an exporter. You can get them from ```localhost:8002/metrics```.
## Suggestions
As mentioned before, Ghoster cannot handle complex functions like HTTP servers. Therefore, it might be good to work on exec component in order to handle complex application. Ghoster resource management is dependent on Go-routines. As they cannot handle some cases, it is a good idea to handle functions used resources.