Viron manages environments, grids, locations, and entities through a clean REST API, serving + * as a reusable backend component for simulation-based games, AI experiments, and virtual world + * applications. + */ @SpringBootApplication -@Import({DbConfig.class, ServiceConfig.class}) public class VironApplication { - public static void main(String[] args) { - SpringApplication.run(VironApplication.class, args); - } - + public static void main(String[] args) { + SpringApplication.run(VironApplication.class, args); + } } diff --git a/src/main/java/preponderous/viron/config/OpenApiConfig.java b/src/main/java/preponderous/viron/config/OpenApiConfig.java index f945645..2fd517c 100644 --- a/src/main/java/preponderous/viron/config/OpenApiConfig.java +++ b/src/main/java/preponderous/viron/config/OpenApiConfig.java @@ -1,17 +1,43 @@ package preponderous.viron.config; import io.swagger.v3.oas.models.OpenAPI; +import io.swagger.v3.oas.models.info.Contact; import io.swagger.v3.oas.models.info.Info; +import io.swagger.v3.oas.models.info.License; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; +/** + * Configuration for OpenAPI documentation. + * + *
This configuration sets up Swagger/OpenAPI documentation for the Viron API, providing + * interactive API documentation accessible via the Swagger UI. + */ @Configuration public class OpenApiConfig { - @Bean - public OpenAPI customOpenAPI() { - return new OpenAPI() - .info(new Info() - .title("Viron API") - .version("0.5.0")); - } -} \ No newline at end of file + + /** + * Creates the OpenAPI configuration bean. + * + * @return configured OpenAPI instance with application metadata + */ + @Bean + public OpenAPI vironOpenAPI() { + return new OpenAPI() + .info( + new Info() + .title("Viron API") + .description( + "Foundational spatial simulation service - the bedrock on which worlds are" + + " built. Manages environments, grids, locations, and entities through a" + + " clean REST API.") + .version("0.6.0-SNAPSHOT") + .contact( + new Contact() + .name("Preponderous Software") + .url("https://github.com/Preponderous-Software/Viron") + .email("support@preponderoussoftware.com")) + .license( + new License().name("MIT License").url("https://opensource.org/licenses/MIT"))); + } +} diff --git a/src/main/java/preponderous/viron/controllers/HealthController.java b/src/main/java/preponderous/viron/controllers/HealthController.java new file mode 100644 index 0000000..24e5df5 --- /dev/null +++ b/src/main/java/preponderous/viron/controllers/HealthController.java @@ -0,0 +1,43 @@ +package preponderous.viron.controllers; + +import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.tags.Tag; +import java.time.LocalDateTime; +import java.util.Map; +import lombok.extern.slf4j.Slf4j; +import org.springframework.http.ResponseEntity; +import org.springframework.web.bind.annotation.GetMapping; +import org.springframework.web.bind.annotation.RequestMapping; +import org.springframework.web.bind.annotation.RestController; + +/** + * Health check controller for monitoring application status. + * + *
Provides endpoints to verify that the Viron application is running and healthy.
+ */
+@RestController
+@RequestMapping("/health")
+@Tag(name = "Health", description = "Application health monitoring")
+@Slf4j
+public class HealthController {
+
+ /**
+ * Basic health check endpoint.
+ *
+ * @return ResponseEntity with health status information
+ */
+ @GetMapping
+ @Operation(summary = "Check application health", description = "Returns basic health status")
+ public ResponseEntity This DTO provides a consistent structure for error responses across all API endpoints,
+ * including timestamp, status code, error message, and request path.
+ */
+@Data
+@AllArgsConstructor
+@NoArgsConstructor
+public class ErrorResponseDto {
+
+ /** Timestamp when the error occurred. */
+ private LocalDateTime timestamp;
+
+ /** HTTP status code. */
+ private int status;
+
+ /** Brief error description. */
+ private String error;
+
+ /** Detailed error message. */
+ private String message;
+
+ /** Request path where error occurred. */
+ private String path;
+}
diff --git a/src/main/java/preponderous/viron/exceptions/BusinessLogicException.java b/src/main/java/preponderous/viron/exceptions/BusinessLogicException.java
new file mode 100644
index 0000000..0fe8b8a
--- /dev/null
+++ b/src/main/java/preponderous/viron/exceptions/BusinessLogicException.java
@@ -0,0 +1,29 @@
+package preponderous.viron.exceptions;
+
+/**
+ * Exception thrown when business logic constraints are violated.
+ *
+ * This exception is used for cases where the request is technically valid but violates business
+ * rules, such as attempting to place an entity in a location that already contains another entity.
+ */
+public class BusinessLogicException extends VironException {
+
+ /**
+ * Constructs a new BusinessLogicException with the specified detail message.
+ *
+ * @param message the detail message describing the business rule violation
+ */
+ public BusinessLogicException(String message) {
+ super(message);
+ }
+
+ /**
+ * Constructs a new BusinessLogicException with the specified detail message and cause.
+ *
+ * @param message the detail message describing the business rule violation
+ * @param cause the cause of this exception
+ */
+ public BusinessLogicException(String message, Throwable cause) {
+ super(message, cause);
+ }
+}
diff --git a/src/main/java/preponderous/viron/exceptions/GlobalExceptionHandler.java b/src/main/java/preponderous/viron/exceptions/GlobalExceptionHandler.java
new file mode 100644
index 0000000..4f27822
--- /dev/null
+++ b/src/main/java/preponderous/viron/exceptions/GlobalExceptionHandler.java
@@ -0,0 +1,123 @@
+package preponderous.viron.exceptions;
+
+import jakarta.servlet.http.HttpServletRequest;
+import java.time.LocalDateTime;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.MethodArgumentNotValidException;
+import org.springframework.web.bind.annotation.ExceptionHandler;
+import org.springframework.web.bind.annotation.RestControllerAdvice;
+import preponderous.viron.dto.ErrorResponseDto;
+
+/**
+ * Global exception handler for the Viron application.
+ *
+ * This class provides centralized exception handling across the entire application, ensuring
+ * consistent error response formats and appropriate HTTP status codes.
+ */
+@RestControllerAdvice
+@Slf4j
+public class GlobalExceptionHandler {
+
+ /**
+ * Handles ResourceNotFoundException and returns a 404 Not Found response.
+ *
+ * @param ex the ResourceNotFoundException
+ * @param request the HTTP request that caused the exception
+ * @return ResponseEntity with error details and 404 status
+ */
+ @ExceptionHandler(ResourceNotFoundException.class)
+ public ResponseEntity This exception is typically thrown when attempting to retrieve an entity by ID that doesn't
+ * exist in the system.
+ */
+public class ResourceNotFoundException extends VironException {
+
+ /**
+ * Constructs a new ResourceNotFoundException with the specified detail message.
+ *
+ * @param message the detail message explaining which resource was not found
+ */
+ public ResourceNotFoundException(String message) {
+ super(message);
+ }
+
+ /**
+ * Constructs a new ResourceNotFoundException with the specified detail message and cause.
+ *
+ * @param message the detail message explaining which resource was not found
+ * @param cause the cause of this exception
+ */
+ public ResourceNotFoundException(String message, Throwable cause) {
+ super(message, cause);
+ }
+}
diff --git a/src/main/java/preponderous/viron/exceptions/VironException.java b/src/main/java/preponderous/viron/exceptions/VironException.java
new file mode 100644
index 0000000..0ac2146
--- /dev/null
+++ b/src/main/java/preponderous/viron/exceptions/VironException.java
@@ -0,0 +1,29 @@
+package preponderous.viron.exceptions;
+
+/**
+ * Base exception class for all Viron-specific exceptions.
+ *
+ * This class serves as the root of the Viron exception hierarchy, providing a common base for
+ * all custom exceptions in the application.
+ */
+public abstract class VironException extends RuntimeException {
+
+ /**
+ * Constructs a new VironException with the specified detail message.
+ *
+ * @param message the detail message explaining the reason for the exception
+ */
+ protected VironException(String message) {
+ super(message);
+ }
+
+ /**
+ * Constructs a new VironException with the specified detail message and cause.
+ *
+ * @param message the detail message explaining the reason for the exception
+ * @param cause the cause of this exception
+ */
+ protected VironException(String message, Throwable cause) {
+ super(message, cause);
+ }
+}
diff --git a/src/main/resources/application.yml b/src/main/resources/application.yml
new file mode 100644
index 0000000..d5578ce
--- /dev/null
+++ b/src/main/resources/application.yml
@@ -0,0 +1,107 @@
+spring:
+ application:
+ name: viron
+
+ profiles:
+ active: dev
+
+ # Database Configuration
+ datasource:
+ url: jdbc:postgresql://localhost:5432/viron
+ username: viron
+ password: password
+ driver-class-name: org.postgresql.Driver
+
+ # JPA Configuration
+ jpa:
+ hibernate:
+ ddl-auto: create-drop
+ show-sql: false
+ properties:
+ hibernate:
+ dialect: org.hibernate.dialect.PostgreSQLDialect
+ format_sql: true
+
+ # API Documentation
+ springdoc:
+ api-docs:
+ path: /api-docs
+ swagger-ui:
+ path: /swagger-ui.html
+
+# Logging Configuration
+logging:
+ level:
+ root: INFO
+ preponderous.viron: DEBUG
+ org.springframework.web: DEBUG
+ org.hibernate.SQL: DEBUG
+ org.hibernate.type.descriptor.sql.BasicBinder: TRACE
+ pattern:
+ console: "%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n"
+ file: "%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n"
+ file:
+ name: logs/viron.log
+
+# Management & Actuator
+management:
+ endpoints:
+ web:
+ exposure:
+ include: health,info,metrics
+ endpoint:
+ health:
+ show-details: when_authorized
+
+# Server Configuration
+server:
+ port: 8080
+ servlet:
+ context-path: /api/v1
+
+---
+# Production Profile
+spring:
+ config:
+ activate:
+ on-profile: prod
+
+ jpa:
+ hibernate:
+ ddl-auto: validate
+ show-sql: false
+
+ datasource:
+ url: ${DATABASE_URL:jdbc:postgresql://localhost:5432/viron}
+ username: ${DATABASE_USERNAME:viron}
+ password: ${DATABASE_PASSWORD:password}
+
+logging:
+ level:
+ root: WARN
+ preponderous.viron: INFO
+ file:
+ name: /var/log/viron/viron.log
+
+---
+# Test Profile
+spring:
+ config:
+ activate:
+ on-profile: test
+
+ datasource:
+ url: jdbc:h2:mem:testdb
+ driver-class-name: org.h2.Driver
+ username: sa
+ password: password
+
+ jpa:
+ hibernate:
+ ddl-auto: create-drop
+ database-platform: org.hibernate.dialect.H2Dialect
+
+logging:
+ level:
+ root: ERROR
+ preponderous.viron: DEBUG
\ No newline at end of file
diff --git a/src/test/java/preponderous/viron/VironApplicationTests.java b/src/test/java/preponderous/viron/VironApplicationTests.java
new file mode 100644
index 0000000..65ac87f
--- /dev/null
+++ b/src/test/java/preponderous/viron/VironApplicationTests.java
@@ -0,0 +1,15 @@
+package preponderous.viron;
+
+import org.junit.jupiter.api.Test;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.test.context.ActiveProfiles;
+
+@SpringBootTest
+@ActiveProfiles("test")
+class VironApplicationTests {
+
+ @Test
+ void contextLoads() {
+ // This test verifies that the Spring application context loads successfully
+ }
+}
diff --git a/src/test/java/preponderous/viron/controllers/HealthControllerTest.java b/src/test/java/preponderous/viron/controllers/HealthControllerTest.java
new file mode 100644
index 0000000..2e1d731
--- /dev/null
+++ b/src/test/java/preponderous/viron/controllers/HealthControllerTest.java
@@ -0,0 +1,26 @@
+package preponderous.viron.controllers;
+
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
+import org.springframework.test.web.servlet.MockMvc;
+
+@WebMvcTest(HealthController.class)
+class HealthControllerTest {
+
+ @Autowired private MockMvc mockMvc;
+
+ @Test
+ void healthEndpointReturnsUpStatus() throws Exception {
+ mockMvc
+ .perform(get("/health"))
+ .andExpect(status().isOk())
+ .andExpect(jsonPath("$.status").value("UP"))
+ .andExpect(jsonPath("$.service").value("Viron Spatial Simulation Service"))
+ .andExpect(jsonPath("$.version").value("0.6.0-SNAPSHOT"));
+ }
+}