An Ignition client cannot execute gateway-scoped code as though that code were local. The client must send a request across the authenticated client-to-gateway channel, the gateway must dispatch that request to a registered RPC service, and the gateway-side implementation must perform the file operation. Follow the packet: client caller, client RPC proxy, network connection, gateway RPC dispatcher, gateway service, then the server filesystem.
Where does the client request stop?
Start by identifying the scope in which each component runs. Code compiled or registered only in gateway scope is absent from the client process. Importing its name, invoking it through reflection, or copying a filesystem path into client code does not cross that process boundary.
| Component | Execution location | Valid responsibility | Invalid assumption |
|---|---|---|---|
| Client script or client module code | Client machine | Collect arguments, invoke the RPC proxy, process the response | A call automatically executes on the gateway |
| RPC transport | Authenticated client-gateway channel | Serialize the request, carry it to the gateway, and return a result or error | The transport grants every user permission to every operation |
| Gateway RPC service | Gateway process | Validate the request, apply authorization, and call gateway logic | Client-provided filenames and paths are inherently safe |
| File operation | Gateway host | Read or write only the intended server-side locations | A path visible to the gateway is also visible to the client |
The decisive reading is the runtime scope. If the file exists only on the gateway host and the working code has gateway access, keep the operation there. Expose a narrow remote operation instead of moving the file code into client scope.
Can the client reach the gateway before RPC starts?
Layer one first. Confirm that the client has a working network interface and a route to the gateway. Then verify name resolution, the configured gateway address, the configured listener port, and the client session state. An RPC implementation cannot repair a disconnected client or a connection aimed at the wrong listener.
| Reading | Where to obtain it | Successful outcome | Failed outcome and next check |
|---|---|---|---|
| Physical or virtual link | Client network status | Interface is up and packets can leave the host | Correct cabling, radio, virtual adapter, or interface configuration |
| Gateway address | Client launch or connection configuration | Name resolves to the intended gateway address | Correct DNS or the configured address before inspecting RPC |
| Listener port | Gateway configuration and client connection settings | Both ends use the same configured port | Correct the setting or intermediate firewall rule; do not guess a port |
| Connection timing | Client diagnostics or packet capture | Connection setup completes without timeout | A timeout points to routing, filtering, or an unavailable listener |
| Authenticated session | Client session diagnostics | The client is connected and authenticated | Resolve authentication or session establishment before testing the method |
Follow one request from the client outward. No connection attempt indicates that client code never reached the proxy call. Repeated connection attempts without a response indicate a network path or listener problem. A connected session followed by an RPC error moves the investigation to registration, serialization, authorization, or gateway execution.
Should the transport be RPC or a web request?
Use Ignition RPC when an Ignition client calls gateway module code. The RPC infrastructure carries the request through an authenticated channel and provides the normal client-to-gateway boundary. The gateway exposes the operation; the client receives a proxy and calls it.
A web route is a separate architectural choice. It is useful when non-Ignition consumers must retrieve data or files, but the route must implement its own authentication, authorization, request validation, response limits, and transport protections. Restricting accessible directories reduces filesystem exposure but does not authenticate a caller.
| Decision | Ignition RPC | Web request |
|---|---|---|
| Caller | Ignition client using the module integration | Ignition or non-Ignition HTTP consumer |
| Channel identity | Uses the authenticated Ignition channel | Must be designed and enforced by the endpoint |
| Authorization | Check applicable roles at the gateway operation | Authenticate the caller, then apply endpoint permissions |
| Interface shape | Remote method with serializable arguments and results | HTTP method, route, headers, body, and status response |
| Correct branch here | Preferred for an Ignition client calling gateway-only logic | Choose when support for non-Ignition clients is an explicit requirement |
Is the RPC contract narrow enough?
Expose an operation, not the gateway filesystem. The request should carry the minimum data needed to identify the operation and resource. Prefer a logical file identifier over an unrestricted absolute path. Resolve that identifier against gateway-controlled configuration, normalize the resulting path, and reject any result outside the allowed root.
Define the contract around serializable values. Inputs can represent a resource identifier and operation options; outputs can represent file content, metadata, or a structured result. Do not return gateway-only objects such as open files, streams tied to gateway resources, or framework contexts. If file content can be large, bound the response or design a controlled streaming or caching path rather than loading an unlimited file into memory.
| Symptom | Likely boundary failure | Reading to take | Next action |
|---|---|---|---|
| Client cannot find the operation | Client contract and gateway registration do not match | Compare the exposed service contract with the gateway implementation | Align the contract, register the gateway service, and restart or reload through the supported module lifecycle |
| Request arrives but arguments fail | Unsupported or mismatched serialization | Inspect client and gateway logs for the rejected argument type | Replace runtime-specific objects with simple serializable data |
| Gateway reports file not found | Identifier resolves to the wrong gateway location | Log the normalized gateway-side target without exposing it to the client | Correct gateway configuration or resource mapping |
| Some users succeed and others fail | Role or session authorization differs | Record authenticated identity and evaluated permission at the gateway | Correct role assignment or the authorization rule |
| Call succeeds but the client stalls | File processing blocks too long or returns excessive data | Measure gateway execution time and response size | Bound the operation, cache appropriate data, or split retrieval into controlled units |
Where must authentication and authorization occur?
The authenticated RPC channel identifies the connected session, but the gateway operation still owns the authorization decision. If every authenticated client may perform the operation, document that rule explicitly. If access depends on roles, evaluate the applicable roles before touching the file.
Validate authorization and arguments in this order: confirm the caller context, apply the operation permission, validate the logical identifier, resolve and normalize the gateway path, verify that the target remains within the configured root, then perform the file action. Return a controlled error that distinguishes denied access, invalid input, missing resources, and gateway execution failure without disclosing sensitive server paths.
Do not accept a client-supplied directory as the security boundary. Inputs containing parent-directory traversal, alternate separators, encoded path components, or absolute paths must not escape the configured root. For write operations, also validate the permitted action, target type, replacement policy, and content limit before opening the destination.
How do you implement the gateway RPC boundary?
- Define the shared contract. Place the remote operation signature in code available to both client and gateway scopes. Use simple serializable arguments and a result that can cross the channel.
- Implement the contract in gateway scope. The implementation receives the request, evaluates authorization, validates inputs, and calls the existing gateway-only script or service that accesses the server files.
- Register the gateway service. Bind the implementation to the module's RPC infrastructure during gateway startup. Remove or replace that registration through the corresponding module lifecycle when required.
- Create the client-side caller. Obtain the remote proxy from the connected client context and invoke the shared operation. Keep filesystem access out of the client branch.
- Handle remote failures. Treat transport failure, authorization denial, invalid input, missing file, and gateway execution failure as different conditions. Report an actionable client message and write diagnostic detail to the appropriate log.
- Control the payload. Reject requests or responses beyond the operation's configured limits. If the requirement is file sharing with non-Ignition clients, implement a separately secured web interface instead of bypassing RPC security.
The data path should now be unambiguous: the client initiates the call, the authenticated channel carries serialized values, the registered gateway service dispatches the method, and only gateway code opens the server file.
How do you verify the resolving branch?
- Call the operation from an authenticated Ignition client with a known valid logical resource identifier.
- Correlate the client invocation with a gateway log entry at RPC dispatch and another at completion. Record outcome and duration, but omit file content and sensitive server paths.
- Confirm that the gateway reads the intended server-side file and that the client receives the expected structured result.
- Repeat with an invalid identifier and verify that validation rejects it before filesystem access.
- Repeat with a path-traversal input and verify that normalization and root containment reject it.
- If roles apply, test one permitted account and one denied account. Confirm that the denied request reaches no file operation.
- Disconnect or block the client-gateway path and verify that the client reports a transport failure rather than a file error.
- Restore connectivity and repeat the valid request, tracing the same client-to-proxy-to-gateway-to-file path.
FAQ
How do I run gateway-only Ignition code from a client?
Expose a shared RPC contract, implement and register it in gateway scope, then call it through a client-side proxy. The gateway implementation, not the client, performs the server file operation.
How do I decide between Ignition RPC and a web request?
Use RPC for an Ignition client because it travels through the authenticated client-gateway channel. Use a web request only when non-Ignition consumers are required, and add endpoint authentication, authorization, validation, and response limits.
How do I prevent an RPC file call from exposing gateway paths?
Accept a logical resource identifier, resolve it against a gateway-controlled root, normalize the path, and reject any target outside that root. Never treat a client-supplied absolute directory as an access-control boundary.
How do I verify that the code actually ran on the gateway?
Correlate one client invocation with gateway dispatch and completion log entries, confirm the intended server file was accessed, and check the returned result. Finish by repeating the valid call after restoring the client-gateway connection and tracing every hop.