abinazebinoy commited on
Commit
0948dec
·
1 Parent(s): 4cdca05

feat(D3): bundled Neo4j Community sidecar process manager

Browse files
Files changed (1) hide show
  1. packaging/neo4j_sidecar.py +168 -0
packaging/neo4j_sidecar.py ADDED
@@ -0,0 +1,168 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """
2
+ BharatGraph Desktop -- bundled Neo4j Community sidecar process manager
3
+ (Phase D3)
4
+
5
+ Zero query-layer changes anywhere else in the codebase -- every
6
+ investigator/route/scraper already speaks to NEO4J_URI via the standard
7
+ neo4j Python driver (verified throughout this project's audit: 130+ Cypher
8
+ call sites, all using a driver that treats the connection as a config
9
+ value, not a "cloud vs local" branch). This module's only job is to make
10
+ sure something real is listening at that URI before the rest of the app
11
+ depends on it, and to stop it cleanly on shutdown -- it does not touch
12
+ graph/, ai/, or api/ at all.
13
+
14
+ Addresses two gaps the audit's Track 2 §10.4 flagged by name:
15
+ - "what happens if a dependent local process -- most relevantly, a
16
+ local Neo4j process, once [local mode] happens -- crashes
17
+ independently of the main app": see restart_if_crashed().
18
+ - Zero process-lifecycle handling existed anywhere in the codebase
19
+ before this (no signal/SIGTERM/atexit/lock-file/port-in-use code):
20
+ this class's stop() is that handling for the Neo4j side specifically.
21
+
22
+ NOT covered here (separate, larger pieces of work): downloading/bundling
23
+ the actual Neo4j Community distribution + minimal JRE into an installer
24
+ (a packaging-pipeline concern, Phase D2/D3's other half), and the
25
+ single-instance-lock / port-in-use detection for the *main* application
26
+ process itself (same gap, but for bharatgraph-backend.exe, not Neo4j).
27
+ """
28
+ import os
29
+ import signal
30
+ import socket
31
+ import subprocess
32
+ import sys
33
+ import time
34
+ from pathlib import Path
35
+ from typing import Optional
36
+
37
+ from loguru import logger
38
+
39
+
40
+ class Neo4jSidecarError(Exception):
41
+ """Raised when the bundled Neo4j sidecar fails to start or become healthy."""
42
+
43
+
44
+ class Neo4jSidecar:
45
+ """Manages a bundled Neo4j Community Server as a child process."""
46
+
47
+ def __init__(
48
+ self,
49
+ neo4j_home: Path,
50
+ bolt_port: int = 7687,
51
+ startup_timeout: float = 60.0,
52
+ ):
53
+ self.neo4j_home = Path(neo4j_home)
54
+ self.bolt_port = bolt_port
55
+ self.startup_timeout = startup_timeout
56
+ self._process: Optional[subprocess.Popen] = None
57
+
58
+ def _neo4j_binary(self) -> Path:
59
+ """Locate the neo4j launcher inside the bundled distribution.
60
+
61
+ Neo4j Community's own distribution layout: <NEO4J_HOME>/bin/neo4j
62
+ (a shell script on Linux/Mac) or neo4j.bat/neo4j.ps1 on Windows.
63
+ """
64
+ candidates = ["neo4j.bat", "neo4j.ps1"] if sys.platform == "win32" else ["neo4j"]
65
+ for name in candidates:
66
+ candidate = self.neo4j_home / "bin" / name
67
+ if candidate.exists():
68
+ return candidate
69
+ raise Neo4jSidecarError(
70
+ f"Could not find a Neo4j launcher in {self.neo4j_home / 'bin'} "
71
+ f"(looked for {candidates}). Is neo4j_home pointing at a real "
72
+ f"Neo4j Community distribution?"
73
+ )
74
+
75
+ @staticmethod
76
+ def _port_open(port: int) -> bool:
77
+ """True if something is actively listening on 127.0.0.1:port."""
78
+ with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
79
+ sock.settimeout(0.5)
80
+ return sock.connect_ex(("127.0.0.1", port)) == 0
81
+
82
+ def is_running(self) -> bool:
83
+ return self._process is not None and self._process.poll() is None
84
+
85
+ def start(self, extra_args: Optional[list] = None) -> None:
86
+ if self.is_running():
87
+ logger.info("[Neo4jSidecar] Already running -- not starting a second instance")
88
+ return
89
+
90
+ binary = self._neo4j_binary()
91
+ logger.info(f"[Neo4jSidecar] Starting bundled Neo4j from {binary}")
92
+
93
+ # "console" mode runs in the foreground as a direct child process
94
+ # (not Neo4j's own daemonizing "start" mode) -- required so this
95
+ # Python process keeps a real subprocess.Popen handle to it, which
96
+ # is what makes clean termination and independent-crash detection
97
+ # possible at all.
98
+ cmd = [str(binary), "console"] + (extra_args or [])
99
+ self._process = subprocess.Popen(
100
+ cmd,
101
+ cwd=str(self.neo4j_home),
102
+ stdout=subprocess.PIPE,
103
+ stderr=subprocess.STDOUT,
104
+ text=True,
105
+ )
106
+
107
+ deadline = time.monotonic() + self.startup_timeout
108
+ while time.monotonic() < deadline:
109
+ if self._process.poll() is not None:
110
+ output = self._process.stdout.read() if self._process.stdout else ""
111
+ code = self._process.returncode
112
+ self._process = None
113
+ raise Neo4jSidecarError(
114
+ f"Neo4j process exited during startup (code {code}). "
115
+ f"Output:\n{output[-2000:]}"
116
+ )
117
+ if self._port_open(self.bolt_port):
118
+ logger.info(
119
+ f"[Neo4jSidecar] Bolt port {self.bolt_port} is accepting "
120
+ f"connections -- ready"
121
+ )
122
+ return
123
+ time.sleep(0.5)
124
+
125
+ self.stop()
126
+ raise Neo4jSidecarError(
127
+ f"Neo4j did not start accepting Bolt connections on port "
128
+ f"{self.bolt_port} within {self.startup_timeout}s"
129
+ )
130
+
131
+ def stop(self, timeout: float = 30.0) -> None:
132
+ if self._process is None:
133
+ return
134
+ if self._process.poll() is not None:
135
+ self._process = None
136
+ return
137
+
138
+ logger.info("[Neo4jSidecar] Stopping bundled Neo4j (graceful)")
139
+ if sys.platform == "win32":
140
+ self._process.terminate()
141
+ else:
142
+ self._process.send_signal(signal.SIGTERM)
143
+
144
+ try:
145
+ self._process.wait(timeout=timeout)
146
+ except subprocess.TimeoutExpired:
147
+ logger.warning(
148
+ f"[Neo4jSidecar] Did not stop gracefully within {timeout}s -- killing"
149
+ )
150
+ self._process.kill()
151
+ self._process.wait(timeout=10)
152
+ self._process = None
153
+
154
+ def restart_if_crashed(self) -> bool:
155
+ """Call periodically (e.g. from a background thread) to detect and
156
+ recover from an independent Neo4j crash -- audit Track 2 §10.4.
157
+ Returns True if a restart was performed.
158
+ """
159
+ if self._process is not None and self._process.poll() is not None:
160
+ code = self._process.returncode
161
+ logger.warning(
162
+ f"[Neo4jSidecar] Neo4j process exited unexpectedly "
163
+ f"(code {code}) -- restarting"
164
+ )
165
+ self._process = None
166
+ self.start()
167
+ return True
168
+ return False