### The origin module contains functions for retrieving relevant origin
### metadata about events (eg: host sending the event).
### 
### The metadata is generated by onramps and is passed down to the tremor
### pipeline as a URI. Internally, the URI is composed of these basic fields:
### 
### * `scheme`
### * `host`
### * `port`
### * `path`
### 
###  The URI format was chosen so that onramps can expose origin information in
### a structured manner, without sacrificing the ability to encode information
### that can vary from onramp to onramp.
### 
### Since the kind and amount of origin information varies based on onramp
### (especially for the path field), the specifics of what each onramp exposes
### is documented in the onramps page.

## Returns the origin URI scheme, or null value if URI is not set. Encodes the
## source of events within tremor (i.e. onramp name).
##
## For example, with udp onramp:
##
## > ```tremor
## > use tremor::system::origin;
## > origin::scheme() == "tremor-udp"
## > ```
##
## Returns `string` or `null`
intrinsic fn scheme() as origin::scheme; 

## Returns the origin URI host, or null value if URI is not set. Encodes the
## source host (usually IP) that sent the event.
##
## For example, with udp onramp and for a test event sent from the same host
## as tremor:
##
## > ```tremor
## > use tremor::system::origin;
## > origin::host() # returns "127.0.0.1"
## > ```
##
## Returns `string` or `null`
intrinsic fn host() as origin::host; 

## Returns the origin URI port, or null value if not set (either the whole URI
## or just the port). Encodes the source port on the host that sent the event.
##
## For example, with udp onramp:
##
## > ```tremor
## > use tremor::system::origin;
## > origin::port() # returns an ephemeral port on the sender host (eg: 41371)
## > ```
##
## Returns `integer` or `null`
intrinsic fn port() as origin::port; 

## Returns the origin URI path as an array (with path segments constituting
## the array members), or null value if URI is not set. Encodes information
## specific to the onramp.
##
## The array structure here allows for capturing multiple details about the
## origin, in a manner that's easily accessible from tremor-script
## (position-based retrieval).
##
## For example, with udp onramp receiving events on port 12202:
##
## > ```tremor
## > use tremor::system::origin;
## > origin::path() # returns ["12202"]
## > ```
##
intrinsic fn path() as origin::path; 


## Returns the full origin URI as a string, or null value if URI is not set.
## The string is of the following standard form (with port as optional):
##
## > `<scheme>://<host>[:<port>]/<path>`
##
## For example, with udp onramp receiving events on port 12202 from the same
## host as tremor:
##
## > ```tremor
## > use tremor::system::origin;
## > origin::as_uri_string() # returns "tremor-udp://127.0.0.1:41371/12202",
## >                        # where 41371 is the ephemeral port on the sending
## >                        # side
## >```
##
intrinsic fn as_uri_string() as origin::as_uri_string; 

## Returns the full origin URI as a record, or null value if URI is not set.
## For example, with udp onramp receiving events on port 12202 from the same
## host as tremor:

## > ```tremor
## > use tremor::system::origin;
## > origin::as_uri_record() == {
## >   "scheme": "tremor-udp",
## >   "host":"127.0.0.1",
## >   "port":41371, # where 41371 is the ephemeral port on the sending side
## >   "path":["12202"]
## > }
## > ```
## 
intrinsic fn as_uri_record() as origin::as_uri_record;