Return distinct exit code for idle timeout shutdown

fixes #91

Author: krisctl

gui/src/actionCreators/actionCreators.spec.js

@@ -1,4 +1,4 @@
-// Copyright 2020-2025 The MathWorks, Inc.
+// Copyright 2020-2026 The MathWorks, Inc.
 
 import configureMockStore from 'redux-mock-store';
 import thunk from 'redux-thunk';
@@ -452,4 +452,53 @@ describe('Test Async actionCreators', () => {
             );
         });
     });
+
+    it('should dispatch REQUEST_SHUTDOWN_INTEGRATION and RECEIVE_SHUTDOWN_INTEGRATION when shutting down without a reason', () => {
+        fetchMock.deleteOnce('./shutdown_integration', {
+            body: {
+                matlab: {
+                    status: 'down'
+                },
+                licensing: null
+            },
+            headers: { 'content-type': 'application/json' }
+        });
+
+        const expectedActionTypes = [
+            actions.REQUEST_SHUTDOWN_INTEGRATION,
+            actions.RECEIVE_SHUTDOWN_INTEGRATION
+        ];
+
+        return store.dispatch(actionCreators.fetchShutdownIntegration()).then(() => {
+            const receivedActions = store.getActions();
+            expect(receivedActions.map((action) => action.type)).toEqual(
+                expectedActionTypes
+            );
+        });
+    });
+
+    it('should dispatch REQUEST_SHUTDOWN_INTEGRATION and RECEIVE_SHUTDOWN_INTEGRATION with reason query param when reason is provided', () => {
+        fetchMock.deleteOnce('./shutdown_integration?reason=IDLE_TIMEOUT', {
+            body: {
+                matlab: {
+                    status: 'down'
+                },
+                licensing: null
+            },
+            headers: { 'content-type': 'application/json' }
+        });
+
+        const expectedActionTypes = [
+            actions.REQUEST_SHUTDOWN_INTEGRATION,
+            actions.RECEIVE_SHUTDOWN_INTEGRATION
+        ];
+
+        return store.dispatch(actionCreators.fetchShutdownIntegration({ reason: 'IDLE_TIMEOUT' })).then(() => {
+            const receivedActions = store.getActions();
+            expect(receivedActions.map((action) => action.type)).toEqual(
+                expectedActionTypes
+            );
+            expect(fetchMock.lastUrl()).toBe('/shutdown_integration?reason=IDLE_TIMEOUT');
+        });
+    });
 });

gui/src/actionCreators/index.js

@@ -1,4 +1,4 @@
-// Copyright 2020-2025 The MathWorks, Inc.
+// Copyright 2020-2026 The MathWorks, Inc.
 
 import {
     SET_TRIGGER_POSITION,
@@ -374,7 +374,7 @@ export function fetchUnsetLicensing () {
     };
 }
 
-export function fetchShutdownIntegration () {
+export function fetchShutdownIntegration ({ reason } = {}) {
     return async function (dispatch) {
         const options = {
             method: 'DELETE',
@@ -383,8 +383,12 @@ export function fetchShutdownIntegration () {
             credentials: 'same-origin'
         };
 
+        const url = reason
+            ? `./shutdown_integration?reason=${encodeURIComponent(reason)}`
+            : './shutdown_integration';
+
         dispatch(requestShutdownIntegration());
-        const response = await fetchWithTimeout(dispatch, './shutdown_integration', options, 15000);
+        const response = await fetchWithTimeout(dispatch, url, options, 15000);
         const data = await response.json();
         dispatch(receiveShutdownIntegration(data));
     };

gui/src/components/App/IdleBufferTimeouts.spec.jsx

@@ -1,7 +1,7 @@
-// Copyright 2024-2025 The MathWorks, Inc.
+// Copyright 2024-2026 The MathWorks, Inc.
 
 // File to test IDLE and BUFFER timeouts.
-// Need a seperate file for mocking BUFFER_TIMEOUT_DURATION before App component is imported for testing.
+// Need a separate file for mocking BUFFER_TIMEOUT_DURATION before App component is imported for testing.
 
 import React from 'react';
 
@@ -73,7 +73,7 @@ describe('Timeouts in App Component', () => {
         });
 
         // Mock fetchShutdownIntegration response
-        fetchMock.deleteOnce('/shutdown_integration', {
+        fetchMock.deleteOnce('/shutdown_integration?reason=IDLE_TIMEOUT', {
             body: createStatusResponse,
             headers: { 'content-type': 'application/json' }
         });
@@ -84,7 +84,7 @@ describe('Timeouts in App Component', () => {
 
         await waitFor(() => {
             expect(fetchMock.called('get_status')).toBe(true);
-            expect(fetchMock.called('shutdown_integration')).toBe(true);
+            expect(fetchMock.called('shutdown_integration?reason=IDLE_TIMEOUT')).toBe(true);
         }, { timeout: initialState.idleTimeoutDuration * 1000 + mockBufferTimeoutDuration * 1000 + additionalTimeForFetchMock * 1000 });
     });
 

gui/src/components/App/index.jsx

@@ -1,4 +1,4 @@
-// Copyright 2020-2025 The MathWorks, Inc.
+// Copyright 2020-2026 The MathWorks, Inc.
 
 import React, { useState, useCallback, useEffect, useMemo, useRef } from 'react';
 import { useSelector, useDispatch } from 'react-redux';
@@ -125,7 +125,7 @@ function App() {
     // BUFFER timer which runs for a BUFFER_TIMER_DURATION more seconds once the IDLE timer has expired to allow the ShutdownWarning
     // dialog box to appear on the screen, such that the user is informed of an impending termination.
     const [, bufferTimerCancel, bufferTimerReset] = useTimeoutFn(() => {
-        dispatch(fetchShutdownIntegration());
+        dispatch(fetchShutdownIntegration({ reason: 'IDLE_TIMEOUT' }));
         setBufferTimerHasExpired(true);
     }, BUFFER_TIMEOUT_DURATION * 1000);
 

matlab_proxy/app.py

@@ -16,7 +16,7 @@
 import matlab_proxy
 from matlab_proxy import constants, settings, util
 from matlab_proxy.app_state import AppState
-from matlab_proxy.constants import IS_CONCURRENCY_CHECK_ENABLED
+from matlab_proxy.constants import IS_CONCURRENCY_CHECK_ENABLED, ExitReason
 from matlab_proxy.util import mwi
 from matlab_proxy.util.mwi import download, token_auth
 from matlab_proxy.util.mwi import environment_variables as mwi_env
@@ -444,6 +444,11 @@ async def shutdown_integration_delete(req):
 
     logger.info(f"Shutting down {state.settings['integration_name']}...")
     state.is_shutting_down = True
+
+    try:
+        state.exit_reason = ExitReason[req.query.get("reason", "").upper()]
+    except KeyError:
+        pass
     res = create_status_response(req.app, "../")
 
     # Schedule the shutdown to happen after the response is sent
@@ -1008,41 +1013,56 @@ def create_and_start_app(config_name):
     Args:
         config_name (str): Name of the configuration to use with matlab-proxy.
     """
-    util.system.configure_no_proxy_in_env(logger)
+    exit_code = int(ExitReason.UNEXPECTED_ERROR)
 
-    # Create, configure and start the app.
-    app = create_app(config_name)
-    app = configure_and_start(app)
+    try:
+        util.system.configure_no_proxy_in_env(logger)
 
-    loop = util.get_event_loop()
+        # Create, configure and start the app.
+        app = create_app(config_name)
+        app = configure_and_start(app)
 
-    # Add signal handlers for the current python process
-    loop = util.add_signal_handlers(loop)
-    try:
-        # Further execution is stopped here until an interrupt is raised
-        loop.run_forever()
+        loop = util.get_event_loop()
 
-    except SystemExit:
-        pass
+        # Add signal handlers for the current python process
+        loop = util.add_signal_handlers(loop)
+        try:
+            # Further execution is stopped here until an interrupt is raised
+            loop.run_forever()
 
-    # After handling the interrupt, proceed with shutting down the server gracefully.
-    try:
-        # aiohttp shutdown to be invoked before cleanup -
-        # https://docs.aiohttp.org/en/stable/web_reference.html#aiohttp.web.Application.shutdown
-        loop.run_until_complete(app.shutdown())
-        loop.run_until_complete(app.cleanup())
+        except SystemExit:
+            pass
 
-        running_tasks = asyncio.all_tasks(loop)
+        # After handling the interrupt, proceed with shutting down the server gracefully.
+        try:
+            # aiohttp shutdown to be invoked before cleanup -
+            # https://docs.aiohttp.org/en/stable/web_reference.html#aiohttp.web.Application.shutdown
+            loop.run_until_complete(app.shutdown())
+            loop.run_until_complete(app.cleanup())
+
+            running_tasks = asyncio.all_tasks(loop)
+
+            # Gracefully cancel all running background tasks
+            loop.run_until_complete(util.cancel_tasks(running_tasks))
+
+        except Exception:
+            pass
 
-        # Gracefully cancel all running background tasks
-        loop.run_until_complete(util.cancel_tasks(running_tasks))
+        state = app["state"]
+        logger.info(
+            f"Finished shutting down (reason: {state.exit_reason.name}, "
+            f"code: {int(state.exit_reason)}). Thank you for using the MATLAB proxy."
+        )
+        loop.close()
+        exit_code = int(state.exit_reason)
+
+    except SystemExit:
+        logger.exception("Unexpected SystemExit raised during execution.")
 
     except Exception:
-        pass
+        logger.exception("Unexpected error caused shutdown.")
 
-    logger.info("Finished shutting down. Thank you for using the MATLAB proxy.")
-    loop.close()
-    sys.exit(0)
+    sys.exit(exit_code)
 
 
 def print_version_and_exit():

matlab_proxy/app_state.py

@@ -19,6 +19,7 @@
     IS_CONCURRENCY_CHECK_ENABLED,
     MATLAB_LOGS_FILE_NAME,
     USER_CODE_OUTPUT_FILE_NAME,
+    ExitReason,
 )
 from matlab_proxy.settings import get_process_startup_timeout
 from matlab_proxy.util import mw, mwi, system, windows
@@ -154,6 +155,7 @@ def __init__(self, settings):
 
         # Flag to track if matlab-proxy is in the process of shutting down
         self.is_shutting_down: bool = False
+        self.exit_reason: ExitReason = ExitReason.NORMAL_SHUTDOWN
 
     def set_remaining_idle_timeout(self, new_timeout):
         """Sets the remaining IDLE timeout after the validating checks.
@@ -220,6 +222,7 @@ async def __decrement_idle_timer(self):
 
         logger.info("The IDLE timer for shutdown has run out...")
         logger.info(f"Shutting down {self.settings['integration_name']}")
+        self.exit_reason = ExitReason.IDLE_TIMEOUT
         await self.stop_matlab()
         loop = util.get_event_loop()
         loop.stop()
@@ -1377,7 +1380,6 @@ async def start_matlab(self, restart_matlab=False):
             await self.__start_window_manager(display)
 
         try:
-
             # Prepare ready file for the MATLAB process.
             self.create_logs_dir_for_MATLAB()
 

matlab_proxy/constants.py

@@ -1,4 +1,5 @@
 # Copyright 2023-2026 The MathWorks, Inc.
+from enum import IntEnum
 from typing import Final, List
 
 """This module defines project-level constants"""
@@ -36,3 +37,16 @@
 
 # Interval in seconds to wait before querying the status of MATLAB.
 CHECK_MATLAB_STATUS_INTERVAL_SECONDS: Final[int] = 1
+
+
+class ExitReason(IntEnum):
+    """Exit reasons for matlab-proxy with distinct exit codes.
+
+    Codes 100+ are application-defined to avoid collision with standard Unix exit codes.
+    Code 0 is retained for normal signal-based shutdown.
+    Code 1 is used for unexpected errors to distinguish from intentional application exits.
+    """
+
+    NORMAL_SHUTDOWN = 0
+    UNEXPECTED_ERROR = 1
+    IDLE_TIMEOUT = 100