Merge branch 'develop' into develop

Author: Krish-Patel656

.github/workflows/go.yml

@@ -25,7 +25,7 @@ jobs:
     - name: Set up Go
       uses: actions/setup-go@v4
       with:
-        go-version: '1.23'
+        go-version: '1.24'
         cache-dependency-path: "**/go.sum"
 
     - name: Setup
@@ -50,7 +50,7 @@ jobs:
     - name: Set up Go
       uses: actions/setup-go@v4
       with:
-        go-version: '1.23'
+        go-version: '1.24'
         cache-dependency-path: "**\\go.sum"
 
     - name: Check & Build

README.md

@@ -1,24 +1,72 @@
+
 # Nebula API
 
 _A database for some really useful UTD data collected by our [tools](https://github.com/UTDNebula/api-tools)._
 
 Project maintained by [Nebula Labs](https://about.utdnebula.com).
 
-### Contributing
-
-Please visit our [Discord](https://discord.utdnebula.com) and talk to us if you'd like to contribute!
-
-### Prerequisites
-
-- Golang 1.23 (or higher)
-
-### Documentation
+## Documentation
 
 Documentation for the current production API can be found [here.](https://api.utdnebula.com/swagger/index.html)
 
-### How to use
+## How to use
 
 - Visit our [Discord](https://discord.utdnebula.com) and ask to be provisioned an API key (please provide details on your use case)
 - Read the documentation listed above (and authenticate with your key for interactive demos)
 - Make requests to `https://api.utdnebula.com` with your provisioned api key set as the `x-api-key` request header
 - **Build cool stuff!**
+
+## Contributing
+Contributions are welcome!
+
+This project uses the MIT License.
+
+Please visit our [Discord](https://discord.utdnebula.com) and talk to us if you'd like to contribute!
+### How to Contribute
+
+Create your own fork by [forking this repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo#forking-a-repository)
+
+[Clone](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo#cloning-your-forked-repository) your forked repository. (Don't forget to install Git if you haven't already)
+
+Submit proposed changes via a [Pull Request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request)
+
+## Building
+### Requirements
+- [Golang 1.23 or Higher](https://go.dev/dl/)
+
+### Building for Windows
+cd into `nebula-api\api`
+
+Setup Go Dependencies with 
+`.\build.bat setup`
+
+Build with
+`.\build.bat build`
+
+Run with
+`.\go-api.exe`
+> Note: some have experienced issues with Windows Defender or other antivirus blocking `go-api.exe` from reading files, editing files, or causing slowed performance. Consider adding a exception to your `nebula-api` folder.
+
+### Building for macOs, Linux, and WSL
+cd into `nebula-api/api`
+
+Setup Go dependencies with 
+`make setup`
+
+Build with
+`make build`
+
+Run with
+`./go-api`
+
+## Running to API locally
+Copy `.env.template` to `.env` with
+`cp .env.template .env`
+
+Enter Nebula MongoDB URI in `.env`
+
+Run `go-api`
+
+Check command output to see the route serving traffic. It's likely port 8080
+
+Visit `http://localhost:8080` to access nebula-api locally

api/Dockerfile

@@ -1,6 +1,6 @@
 # syntax=docker/dockerfile:1
 
-FROM docker.io/golang:1.23 AS builder
+FROM docker.io/golang:1.24 AS builder
 WORKDIR /build
 
 COPY ./configs ./configs

api/controllers/astra.go

@@ -2,6 +2,7 @@ package controllers
 
 import (
 	"context"
+	"errors"
 	"net/http"
 	"time"
 
@@ -19,6 +20,7 @@ var astraCollection *mongo.Collection = configs.GetCollection("astra")
 
 // @Id				AstraEvents
 // @Router			/astra/{date} [get]
+// @Tags			Events
 // @Description	"Returns AstraEvent based on the input date"
 // @Produce		json
 // @Param			date	path		string																true	"date (ISO format) to retrieve astra events"
@@ -41,3 +43,114 @@ func AstraEvents(c *gin.Context) {
 
 	respond(c, http.StatusOK, "success", astra_events)
 }
+
+// @Id				AstraEventsByBuilding
+// @Router			/astra/{date}/{building} [get]
+// @Tags			Events
+// @Description	"Returns AstraEvent based on the input date and building name"
+// @Produce		json
+// @Param			date		path		string																true	"date (ISO format) to retrieve astra events"
+// @Param			building	path		string																true	"building abbreviation of event locations"
+// @Success		200			{object}	schema.APIResponse[schema.SingleBuildingEvents[schema.AstraEvent]]	"All sections with meetings on the specified date in the specified building"
+// @Failure		500			{object}	schema.APIResponse[string]											"A string describing the error"
+// @Failure		404			{object}	schema.APIResponse[string]											"A string describing the error"
+func AstraEventsByBuilding(c *gin.Context) {
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	date := c.Param("date")
+	building := c.Param("building")
+
+	var astra_events schema.MultiBuildingEvents[schema.AstraEvent]
+	var astra_eventsByBuilding schema.SingleBuildingEvents[schema.AstraEvent]
+
+	// Find astra event given date
+	err := astraCollection.FindOne(ctx, bson.M{"date": date}).Decode(&astra_events)
+	if err != nil {
+		if errors.Is(err, mongo.ErrNoDocuments) {
+			astra_events.Date = date
+			astra_events.Buildings = []schema.SingleBuildingEvents[schema.AstraEvent]{}
+		} else {
+			respondWithInternalError(c, err)
+			return
+		}
+	}
+
+	//parse response for requested building
+	for _, b := range astra_events.Buildings {
+		if b.Building == building {
+			astra_eventsByBuilding = b
+			break
+		}
+	}
+
+	if astra_eventsByBuilding.Building == "" {
+		c.JSON(http.StatusNotFound, schema.APIResponse[string]{
+			Status:  http.StatusNotFound,
+			Message: "error",
+			Data:    "No events found for the specified building",
+		})
+		return
+	}
+
+	respond(c, http.StatusOK, "success", astra_eventsByBuilding)
+}
+
+// @Id				AstraEventsByBuildingandRoom
+// @Router			/astra/{date}/{building}/{room} [get]
+// @Tags			Events
+// @Description	"Returns AstraEvent based on the input date building name and room number"
+// @Produce		json
+// @Param			date		path		string																true	"date (ISO format) to retrieve astra events"
+// @Param			building	path		string																true	"building abbreviation of event locations"
+// @Param			room		path		string																true	"room number for event"
+// @Success		200			{object}	schema.APIResponse[schema.SingleBuildingEvents[schema.AstraEvent]]	"All sections with meetings on the specified date in the specified building"
+// @Failure		500			{object}	schema.APIResponse[string]											"A string describing the error"
+// @Failure		404			{object}	schema.APIResponse[string]											"A string describing the error"
+func AstraEventsByBuildingAndRoom(c *gin.Context) {
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	date := c.Param("date")
+	building := c.Param("building")
+	room := c.Param("room")
+
+	var astra_events schema.MultiBuildingEvents[schema.AstraEvent]
+	var roomEvents schema.RoomEvents[schema.AstraEvent]
+
+	// Find astra event given date
+	err := astraCollection.FindOne(ctx, bson.M{"date": date}).Decode(&astra_events)
+	if err != nil {
+		if errors.Is(err, mongo.ErrNoDocuments) {
+			astra_events.Date = date
+			astra_events.Buildings = []schema.SingleBuildingEvents[schema.AstraEvent]{}
+		} else {
+			respondWithInternalError(c, err)
+			return
+		}
+	}
+
+	//parse response for requested building and room
+	for _, b := range astra_events.Buildings {
+		if b.Building == building {
+			for _, r := range b.Rooms {
+				if r.Room == room {
+					roomEvents = r
+					break
+				}
+			}
+			break
+		}
+	}
+
+	if roomEvents.Room == "" {
+		c.JSON(http.StatusNotFound, schema.APIResponse[string]{
+			Status:  http.StatusNotFound,
+			Message: "error",
+			Data:    "No rooms found for the specified building or event",
+		})
+		return
+	}
+
+	respond(c, http.StatusOK, "success", roomEvents)
+}

api/controllers/autocomplete.go

@@ -19,6 +19,7 @@ var DAGCollection *mongo.Collection = configs.GetCollection("DAG")
 
 // @Id				autocompleteDAG
 // @Router			/autocomplete/dag [get]
+// @Tags			Other
 // @Description	"Returns an aggregation of courses for use in generating autocomplete DAGs"
 // @Produce		json
 // @Success		200	{object}	schema.APIResponse[[]schema.Autocomplete]	"An aggregation of courses for use in generating autocomplete DAGs"

api/controllers/controller_utils.go

@@ -9,17 +9,52 @@ import (
 	"github.com/getsentry/sentry-go"
 	sentrygin "github.com/getsentry/sentry-go/gin"
 	"github.com/gin-gonic/gin"
+	"go.mongodb.org/mongo-driver/bson"
 	"go.mongodb.org/mongo-driver/bson/primitive"
 )
 
 // Sets the API's response to a request, producing valid JSON given a status code and data.
 func respond[T any](c *gin.Context, status int, message string, data T) {
-	c.JSON(status, schema.APIResponse[T]{Status: status, Message: message, Data: data})
+	c.JSON(
+		status,
+		schema.APIResponse[T]{
+			Status:  status,
+			Message: message,
+			Data:    data,
+		},
+	)
+}
+
+// Builds a MongoDB filter for type T based on the given flag search or byid
+func getQuery[T any](flag string, c *gin.Context) (bson.M, error) {
+	switch flag {
+	case "Search":
+		query, err := schema.FilterQuery[T](c)
+		if err != nil {
+			respond(c, http.StatusBadRequest, "Invalid query parameters", err.Error())
+			return nil, err
+		}
+		return query, nil
+
+	case "ById":
+		objId, err := objectIDFromParam(c, "id")
+		if err != nil {
+			// objectIDFromParam already responds with 400 if conversion fails
+			return nil, err
+		}
+		return bson.M{"_id": objId}, nil
+
+	default:
+		err := fmt.Errorf("invalid flag for getQuery: %s", flag)
+		respondWithInternalError(c, err)
+		return nil, err
+	}
 }
 
 // Helper function for logging and responding to a generic internal server error.
 func respondWithInternalError(c *gin.Context, err error) {
-	// Note that we use log.Output here to be able to set the stack depth to the frame above this one (2), which allows us to log the location this function was called from
+	// Note that we use log.Output here to be able to set the stack depth to the frame above this one (2),
+	// which allows us to log the location this function was called from
 	log.Output(2, fmt.Sprintf("INTERNAL SERVER ERROR: %s", err.Error()))
 	// Capture error with Sentry
 	if hub := sentrygin.GetHubFromContext(c); hub != nil {
@@ -30,14 +65,19 @@ func respondWithInternalError(c *gin.Context, err error) {
 	respond(c, http.StatusInternalServerError, "error", err.Error())
 }
 
-// Attempts to convert the given parameter to an ObjectID for use with MongoDB. Automatically responds with http.StatusBadRequest if conversion fails.
+// Attempts to convert the given parameter to an ObjectID for use with MongoDB.
+// Automatically responds with http.StatusBadRequest if conversion fails.
 func objectIDFromParam(c *gin.Context, paramName string) (*primitive.ObjectID, error) {
 	idHex := c.Param(paramName)
 	objectId, convertIdErr := primitive.ObjectIDFromHex(idHex)
 	if convertIdErr != nil {
 		// Respond with an error if we can't covert successfully
 		log.Println(convertIdErr)
-		respond(c, http.StatusBadRequest, fmt.Sprintf("Parameter \"%s\" is not a valid ObjectID.", paramName), convertIdErr.Error())
+		respond(c,
+			http.StatusBadRequest,
+			fmt.Sprintf("Parameter \"%s\" is not a valid ObjectID.", paramName),
+			convertIdErr.Error(),
+		)
 		return nil, convertIdErr
 	}
 	return &objectId, nil