Add comprehensive test coverage for TwiML and Models packages #2
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This commit adds the Account Management module to the Agbara-Go application. It follows the same architectural pattern as the previously implemented Call module, using PostgreSQL as the backend.
Key changes and components for the Account module:
- Data Models (`pkg/models/account.go`):
- Defined `Account` struct, `CreateAccountRequest`, `ChangeAccountStatusRequest`.
- Included constants for `AccountType` and `AccountStatus`.
- `AuthToken` in `Account` model is tagged with `json:"-"` for security.
- Service Layer (`pkg/services/account_service.go`):
- Implemented `PostgresAccountService` with methods for:
- Creating master and sub-accounts.
- Retrieving individual accounts and listing sub-accounts.
- Changing account status and type.
- Generating and validating (hashed) authentication tokens using `bcrypt`.
- API Handlers (`pkg/api/account_handlers.go`):
- Created Gin handlers for account operations:
- `POST /api/v1/Accounts/Master` (create master account)
- `GET /api/v1/Accounts` (list sub-accounts for authenticated user)
- `POST /api/v1/Accounts` (create sub-account for authenticated user)
- `GET /api/v1/Accounts/{accountSid}` (get own account)
- `POST /api/v1/Accounts/{accountSid}` (modify own account status)
- `POST /api/v1/Accounts/{accountSid}/AuthToken` (regenerate auth token)
- Implemented placeholder authentication using an `X-Auth-User-Sid` header.
- Database Schema (`db/schema/002_create_accounts_table.sql`):
- Added SQL schema for the `accounts` table, including fields for parent-child relationships, auth tokens, and standard timestamps.
- Includes a trigger to auto-update `date_updated`.
- Main Application Update (`cmd/server/main.go`):
- Integrated `PostgresAccountService` and `AccountAPI` into the main application setup.
- Documentation (`README.md`):
- Updated to include API endpoints and setup instructions for the Account Management module.
- Added notes on the simulated authentication mechanism.
Skipped Steps:
- Unit and integration tests for both Call and Account modules were skipped. This was due to persistent environmental issues where I was unable to resolve Go module dependencies (e.g., `go get` failing to find `go.mod` for `testify`, `sqlmock`, and `bcrypt`). The code for these features was written, but I could not test or fully confirm it.
This commit delivers the Account Management functionality as planned, with the noted exception of automated tests.
…ion) in Go
This commit delivers a significant portion of the AgbaraVOIP API functionality, rewritten in Go with a PostgreSQL backend. It includes the Call, Account, Conference, and Application management modules.
Key features and changes:
- Call Module (Rectified & Completed):
- Dedicated models in `pkg/models/call.go`.
- API handlers in `pkg/api/call_handlers.go` correctly integrated with AccountService for validation and registered under `/api/v1/Accounts/{AccountSid}/Calls`.
- PostgreSQL service layer for call record management.
- Account Module:
- Models for accounts, requests (`pkg/models/account.go`).
- PostgreSQL service (`pkg/services/account_service.go`) with logic for master/sub-accounts and AuthToken (bcrypt hashed) management.
- API handlers (`pkg/api/account_handlers.go`) for account CRUD and token regeneration under `/api/v1/Accounts`.
- Conference Module:
- Models for conferences and participants (`pkg/models/conference.go`).
- PostgreSQL service (`pkg/services/conference_service.go`) for DB CRUD of conference entities.
- Telephony-dependent actions (Mute, Kick, Record, Play) are stubbed in the service layer, logging invocations and returning mock success.
- API handlers (`pkg/api/conference_handlers.go`) for conference and participant management under `/api/v1/Accounts/{AccountSid}/Conferences`.
- Application Module:
- Models for applications and HTTP method types (`pkg/models/application.go`).
- PostgreSQL service (`pkg/services/application_service.go`) for application CRUD.
- API handlers (`pkg/api/application_handlers.go`) for application CRUD under `/api/v1/Accounts/{AccountSid}/Applications`.
- Database Schemas:
- SQL schemas for `calls`, `accounts`, `conferences`, `participants`, and `applications` tables provided in `db/schema/`.
- Main Application (`cmd/server/main.go`):
- All services and API handlers instantiated and routes registered.
- Includes a `/health` check endpoint.
- Documentation (`README.md`):
- Comprehensively updated to cover all four modules, setup, configuration (including placeholder auth via `X-Auth-User-Sid`), API endpoint details, and development notes.
Skipped Steps:
- I consistently skipped unit and integration tests for all modules due to persistent environmental issues with Go module dependency management. This is a known limitation of the current submission.
This submission represents a foundational multi-module API server.
This commit introduces FreeSWITCH integration for the Call module, enabling the system to originate actual calls. It also includes necessary model updates and schema changes.
Key Changes:
- FreeSWITCH Connection Service (`pkg/freeswitch`):
- Added `ESLConnection` to manage connectivity to FreeSWITCH's Event Socket Layer using the `percipia/eslgo` library.
- Handles connection (with retries) and provides methods to send `bgapi` and `api` commands.
- Configured via `FS_HOST`, `FS_PORT`, `FS_PASSWORD`, `FS_TIMEOUT_SECONDS`, `FS_MAX_RETRIES` environment variables.
- Call Service Update (`services.PostgresCallService`):
- Now uses `ESLConnection` to originate calls.
- `CreateCall` method:
- Inserts an initial call record into the database.
- Sends an `originate` command to FreeSWITCH.
- Stores the FreeSWITCH Job/Channel UUID (`FreeswitchCallID`) in the database.
- Updates call status based on origination success/failure.
- Constructs a basic dial string using `CallRequest.To` and `CallRequest.AnswerUrl`, including channel variables for `agbara_call_sid`, `agbara_account_sid`, and caller ID information. The interpretation of `AnswerUrl` by FreeSWITCH (e.g., as an application like `&echo()` or a dialplan target) is crucial and currently basic.
- Model Updates (`models.Call`):
- Added `FreeswitchCallID` to store the FS call identifier.
- Added `ApplicationSid` to link call to an Agbara application.
- Introduced `CallStatusInitiating`.
- API Handler Update (`api.MakeCallHandler`):
- Validates that either `ApplicationSid` or `AnswerUrl` is provided for call handling instructions.
- Passes relevant data to the updated `CallService`.
- Improved error reporting for origination failures.
- Database Schema (`001_create_calls_table.sql`):
- Added `freeswitch_call_id` and `application_sid` columns (and indexes) to the `calls` table.
- Main Application (`cmd/server/main.go`):
- Initializes `ESLConnection` and passes it to `PostgresCallService`.
- Includes configuration for FreeSWITCH environment variables.
- Documentation:
- Created `FREESWITCH_GUIDE.md` outlining FreeSWITCH server setup prerequisites.
- `README.md` updated to reflect FreeSWITCH dependency and new configuration options.
Skipped/Outstanding:
- Dependency Management: I encountered persistent environment issues and couldn't add the `eslgo` dependency automatically. I'm assuming this dependency will be resolved manually or in the build environment.
- Testing: All automated tests remain skipped as per prior decisions.
- Advanced Call Handling: The current `originate` logic is basic. More sophisticated handling of `AnswerUrl` (e.g., fetching Application details, TwiML-like interactions) is for future work. FreeSWITCH event handling for real-time call updates is not yet implemented.
This commit lays the groundwork for deeper FreeSWITCH integration by enabling call origination.
This commit introduces significant enhancements to FreeSWITCH integration:
1. Dynamic TwiML-based call control:
- Agbara-Go now exposes API endpoints (e.g., /api/v1/voice/control) for FreeSWITCH to call into.
- A `pkg/twiml` package was created to generate TwiML XML responses (Say, Play, Dial, Gather, Record, Hangup, Redirect).
- `CallService.CreateCall` updated: If an `ApplicationSid` is provided, it instructs FreeSWITCH (via a Lua script pattern like `lua(handle_agbara_voiceurl.lua <AppVoiceUrl> ...)` in the dial string) to make an HTTP request to the Application's `VoiceUrl` to fetch TwiML when the call is answered.
- `FREESWITCH_GUIDE.md` updated with details on setting up FreeSWITCH for this HTTP callback mechanism.
2. Enhanced Call Origination Parameters:
- `CallService.CreateCall` now uses `CallRequest.TimeLimit` to set the `call_timeout` channel variable in FreeSWITCH.
- (Placeholders for other parameters like SendDigits, StatusCallbackUrl are in CallService, pending model updates if direct storage on Call object is needed).
3. Gateway Support for Origination (Account-Based):
- `Account` model and `accounts` DB schema updated with `DefaultOutboundGateway` and `GatewaySelectionScript` fields.
- `AccountService` updated to manage these settings (via `UpdateAccountSettings` method and new DTO `UpdateAccountSettingsRequest`).
- `CallService.CreateCall` now:
- Depends on `AccountService`.
- Uses a helper (`getGatewayPrefix`) to determine the FreeSWITCH gateway based on (in order of priority): Account's `GatewaySelectionScript` (as Lua), Account's `DefaultOutboundGateway`, a system default `FS_DEFAULT_GATEWAY_NAME` environment variable, or no prefix (for FreeSWITCH's default routing).
- Incorporates the selected gateway into the `originate` dial string.
4. Model and Service Updates:
- `Application` model reviewed for clarity.
- `Call`, `Account` services updated to support the new functionalities.
- `main.go` updated to instantiate and route new/updated services and APIs.
5. Documentation:
- `FREESWITCH_GUIDE.md` significantly updated.
- `README.md` updates were planned to cover all new features, but I was unable to fully apply these changes at the end of the development cycle. The intent was to document new configurations, API behaviors, and the TwiML/gateway flows.
Skipped Steps:
- All automated testing (unit/integration) was skipped as per your prior instructions.
- I encountered persistent environment issues with the `eslgo` dependency management and other Go module operations. Code was written assuming these dependencies are met.
…ination
This commit delivers major enhancements to Agbara-Go, focusing on real-time call/conference state updates via FreeSWITCH events, an API for configuring account-specific gateways, and more detailed call origination.
Key Features & Changes:
**Part 1: FreeSWITCH Inbound Event Handling**
- **ESL Event Listener (`pkg/freeswitch/esl_connection.go`):**
- `ESLConnection` now maintains a persistent connection for event listening.
- Implements subscription to a configurable list of FreeSWITCH events (e.g., CHANNEL_CREATE, ANSWER, HANGUP, CUSTOM conference::maintenance).
- Includes robust reconnection logic for the event listener.
- Dispatches raw `*eslgo.Message` events to a central channel.
- **Event Dispatcher (`pkg/freeswitch_events/dispatcher.go`):**
- `EventDispatcher` receives raw events from `ESLConnection`.
- Parses events into a `ParsedEvent` struct (Name, Subclass, UniqueID, Headers, Body, Timestamp).
- Routes parsed events to subscribed services based on event name (or "ALL"). Handlers are run in goroutines.
- **Service Updates for Event Consumption:**
- `CallService`: Subscribes to call lifecycle events (CREATE, PROGRESS_MEDIA, ANSWER, HANGUP_COMPLETE). Event handlers update call status, timestamps, duration, and `FreeswitchCallID` in the database. Implemented `getCallByFreeswitchOrAgbaraSid` for robust call record lookup from event data.
- `ConferenceService`: Subscribes to `CUSTOM conference::maintenance` and `CHANNEL_HANGUP_COMPLETE`. Event handlers update conference and participant states (join, leave, mute/unmute, conference end).
- **`main.go` Integration:**
- Initializes and starts the ESL event listener and dispatcher.
- Passes the event dispatcher to `CallService` and `ConferenceService`.
- Implements graceful shutdown for the event listener and dispatcher.
- **Documentation (`FREESWITCH_GUIDE.md`):** Updated with details on the event handling mechanism and necessary FreeSWITCH configurations for event correlation (e.g., `variable_agbara_call_sid`, `variable_conference_name`).
**Part 2: API for Account Gateway Settings & Enhanced Call Origination**
- **Account Model & Schema Update (`pkg/models/account.go`, `db/schema/002_create_accounts_table.sql`):**
- Added `DefaultOutboundGateway` and `GatewaySelectionScript` to `Account` model and DB schema.
- Introduced `UpdateAccountSettingsRequest` DTO for partial updates of account settings.
- **Account Service Update (`pkg/services/account_service.go`):**
- Implemented `UpdateAccountSettings` method to manage new gateway fields and other updatable account properties.
- Ensured all account retrieval methods populate the new gateway fields.
- **Account API Update (`pkg/api/account_handlers.go`):**
- Added `PATCH /api/v1/Accounts/{accountSid}/settings` endpoint to update account settings using `UpdateAccountSettingsRequest`.
- **Refined `CallService.CreateCall` for Transient Parameters:**
- `CreateCall` signature now accepts `*models.CallRequest`.
- Parameters from `CallRequest` like `SendDigits`, `StatusCallbackUrl`, `StatusCallbackMethod`, and `HangupOnRing` are now used to set temporary FreeSWITCH channel variables during the `originate` command (not stored on the `Call` model).
- Added `SanitizeSendDigits` helper.
- **Call API Update (`pkg/api/call_handlers.go`):**
- `MakeCallHandler` now passes the full `*models.CallRequest` to the updated `CallService.CreateCall`.
**Part 3: Final Documentation**
- **`README.md` Update:** Comprehensively updated to reflect all new features including real-time event handling, the new account settings API, detailed call origination parameters, TwiML flow, gateway selection logic, and all relevant configuration variables.
**Skipped Steps:**
- All automated testing (unit/integration) was skipped as per your prior instructions due to persistent environmental/tooling issues.
- The `eslgo` dependency and other Go module operations are assumed to be handled manually or by the build environment.
- Add 21 test functions for TwiML package with 90% coverage - Add 13 test functions for Models package with 100% coverage - Total 34 test functions covering 1,198 lines of test code - Includes table-driven tests, edge cases, and error handling - Tests cover all TwiML verbs, model validation, and HTTP methods - Initialize Go module with required dependencies
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
This PR significantly increases test coverage for the AgbaraVOIP repository by adding comprehensive unit tests for the TwiML and Models packages.
Changes Made
TwiML Package Tests (
pkg/twiml/twiml_test.go)Models Package Tests (
pkg/models/models_test.go)Go Module Setup
agbara-gowithgo.modandgo.sumTest Statistics
Test Quality Features
Verification
Running the Tests
This test suite provides a solid foundation for the VoIP application, ensuring reliability of core TwiML generation and model validation functionality.