/ 
Neo4j-Driver-0.47
River stage one • 1 direct dependent • 2 total dependents
/ TODO+.pod

TODO

NEW, not yet prioritised, possibly urgent

  • nothing

Definitely before last 0.xx release

  • Various urgent docs updates NOT directly related to upcoming 1.00 release

    • Bytes.pm: remove from PodWeaver

    • In Deprecations (get_bool): Perl now has native bools

    • Move _run_multiple docs from Transaction to Deprecations

    • Clarify somewhere that currently only HTTP 1.1 has first-party support (because most of the Perl HTTP clients don't support newer HTTP versions). Adding this to Net would work, but for future-proofing it, it should perhaps be mentioned in the bundled HTTP adapter as well. Since the adapter is a properly declared and documented dependency, this clarification is not very urgent. See also: https://neo4j.com/docs/operations-manual/5/configuration/configuration-settings/#config_server.http_enabled_transports

  • I feel like I should allow 'v2' (and possibly even just '2') for cypher_params. It's such a simple change and makes the feature that much more stable. It's also listed for the config rework below, but this change might really be worth making already now. (On the other hand, the same argument could be made for the new summary time methods and prolly a few other things. Maybe best to not delay 1.00 for anything. But perhaps selected changes are so simple and so useful that they could happen quickly.)

    -------------------

  • Various docs updates related to upcoming 1.00 release

    • Replace summary() with consume(), version() with agent() in synopsis for: Neo4j::Driver::ResultSummary, Neo4j::Driver::SummaryCounters

    • check SEE ALSO sections

    • maybe try to finally figure out the podweaver thing (see Plugin pod); what if I simply avoid "DESCRIPTION" as a header, does that solve anything? (I have a provisional workaround in a git stash, prolly good enough)

    • remove the installed TODO file, remove BUGS/ENV sections in Driver.pm, remove POD from StatementResult/Temporal

    • check/rewrite all synopsis on all classes

    • remove references to "my CPAN email address" (eg in Plugin)

    • replace references to libneo4j-client with libneo4j-omni (eg in Net), but ONLY if Neo4j::Client is updated before the release

    • "run" in Neo4j::Driver::Transaction: replace \1 with \builtin::true

Not sure

Doesn't really matter when:

  • Check Neo4p for deprecated / internal stuff, offer PR if necessary or maybe fix directly.

Must be in the 1.00 release

  • Make concurrent transactions warning fatal

  • Remove ResultColumns, deprecated modules, deprecated features

Shortly after the 1.00 release

may happen in 1.00 already:

  • Remove docs for _run_multiple()

  • Deprecate discouraged features (including summary() in Record)

  • Bump prereq versions (Bolt, Types, maybe even perl)

  • Remove Type::Bytes and use the generic type instead (requires Types v2); also, the Types generic constructor should prolly accept the JSON int array, so that users at least have a simple way to manually get a unified API.

  • General refactoring, e. g. change user-visible strings to be single-line sprintf (ability to grep for them), remove check for $ENV{NO_NEO4J_CORE_BOOLS} etc.

  • General docs update, e. g. add "special thanks", remove "official equivalent", abc in "Constructed values" in Neo4j::Driver::Types, have the run() mapping example use core bools or remove it entirely, check that Net.pod features section is still true and update it or remove the file entirely, rephrase buffering, adjust "execute_write" in Neo4j::Driver::Session to say that returning Result objects is always undefined behaviour (not just for Bolt), adjust docs for prereqs based on version changes (e. g. "protocol_version" won't need the 0.20 note anymore) etc.

should NOT happen in 1.00 itself:

  • Drop Bolt deep_bless. This requires perlbolt Types v2 support though. (I really want this, but a lot of other changes are even more important, which is why this item is not at the top of the list.)

  • Refactor Node etc. to match the Jolt data structures instead of JSON; refactor Record to be implemented as just a single array representing the row, with the (get("2")-fixed) column lookup hash appended at the array's end

  • Neo4j::Driver::Net::HTTP::Tiny

  • Discourage list() (in Result) in scalar context, maybe formally discourage concurrent_tx

  • Possibly prevent size() (in Result) from exhausting the result stream. It would be enough to detach the stream. The reason we even have size() is only because list() in scalar context gives an array ref, so there is no real reason for it to exhaust the result stream. Preventing this might perhaps be useful in some scenarios.

  • Config rework

    • The big plan is to have a config object that can be used anywhere (driver/session/tx), with any settings not required in a context simply ignored. A config object would be created on the fly if a hash ref is provided. Each context will merge the given config with whatever has been supplied to the higher-level context, providing a mechanism for custom default values.

    • Problem is, doing it right is a fair amount of work and I might not want to delay 1.00 for it.

    • => don't make {config} a real object until after 1.00 unless absolutely necessary (at most, turn it into a .pm file that has a hidden config() method so it can proxy for what is now the $driver in many cases, but completely hide the fact that it's an object in the docs, otherwise it's just a new API wormhole)

    • Use none {} LIST in unsupported option check

    • Add transaction configuration

    • Probably add bookmark support

    • Fix memory leak in Neo4j::Driver::Net::HTTP

    • allow "v2" as value for cypher_params

    • part of the config rework is also plugin access to the configuration (likely through the first_session and parse_uri events, but possibly also a more generic config event)

    • Jolt results: if concurrent_tx, then enforce gather_results

  • Possible docs improvement: add "since version 0.xx" to all methods, referring to the point when the method itself was added

Address open issues on GitHub

See https://github.com/johannessen/neo4j-driver-perl/issues.

Functionality and API

Tests, code quality, documentation

  • Improve test coverage:

    • Many yet uncovered code paths are obviously fine, but difficult or impossible to cover. In some of these cases, it may be possible to refactor the code, such as by banking on autovivification (i.e. don't defend against undefined $a in expressions like $a->{b}; see "Using References" in perlref).

    • The deep_bless subs contain a lot of assertions and other checks that are not normally necessary. Since this logic seems to work fine, it should be simplified. (This may also make it easier to unroll the recursion later.)

    • Documenting each attribute in Neo4j::Driver::SummaryCounters as individual methods might be a quick way to bring up the pod coverage stats a bit.

  • Write new unit tests for all modules. Tests should probably live in files with names that are a good match for module names, so that it's easy to find test for a specific module (Simulator and live tests should perhaps be in separate files and directories.) The article Perl Testing in 2023 has some insight into how Test2 can simplify unit tests.

  • Optimise the simulator for $hash = 0. Use of << causes statements to end with \n, which the simulator could filter out. The internals test "transaction: REST 404 error handling" should run a distinct statement.

  • Consider migrating the LWP tests away from Mock::Quick to reduce the dependency chain (Mock::MonkeyPatch and Mock::Sub look extremely light-weight, alternatives might perhaps be Test::MockObject::Extends or Test::LWP::UserAgent; there is also Sub::Override).

  • Verify that "get" in Neo4j::Driver::Type::Node and "get" in Neo4j::Driver::Type::Relationship really do return undef (as documented), even when called in list context.

  • We need complete working code examples, such as that Neo4j movies app. Some of the deprecated functionality could also be implemented as plug-ins in a dist named e. g. Neo4j::Driver::Net::HTTP::Extra. Such a plug-in might be directly useful to some users, but most importantly, it would serve to demonstrate some of the plug-in API's functionality and how that can be used.

Other ideas for specific modules

Neo4j::Driver

  • neo4j URI scheme support: Ideally, the driver's config method would continue to return 'neo4j' even after the session is created.

  • Convert the "unsupported option" check from grep to "none" in List::Util (in config() and _parse_options(); slightly improves both performance and clarity).

  • A reliable connection_timeout config option might be good. Not exactly sure how to achieve that across Bolt, LWP etc. Googling yields IO::Socket::Timeout and SocketConnectTimeout, but I haven't really researched further.

Neo4j::Driver::Events

  • The default implementation of the "error" event currently tries to more or less recreate the old error message strings. Looking forward, having Neo4j::Error overload stringification and just throwing an object exception might be an interesting option. However, we likely would have to roll croak ourselves (see "BUGS" in Carp). See https://perldoc.perl.org/functions/die for the special meaning of \n.

Neo4j::Driver::Session

Neo4j::Driver::Transaction

  • Run statements lazily: Just like with the official drivers, statements passed to run should be gathered until their results are actually accessed. Then, and only then, all statements gathered so far should be sent to the server using a single request. Challenges of this approach include that notifications are not associated with a single statement, so there must be an option to disable this behaviour; indeed, disabled should probably be the default when stats are requested. Additionally, there are some bugs with multiple statements (see tests non-arrayref individual statement and include empty statement). Since stats are now requested by default, this item might mean investing time in developing an optimisation feature that is almost never used. Since the server is often run on localhost anyway where latency is very close to zero, this item should not have high priority.

  • Support for bookmarks was added to HTTP in Neo4j 5.6.

Neo4j::Driver::Record

Neo4j::Driver::Result

  • Improve documentation, esp. wrt. side-effects of e. g. has_next()

  • Perhaps fetch() should always buffer two records instead of just one. With the current implementation, the bolt connection might remain attached longer than desirable in cases where the client knows in advance how many records there will be and calls fetch() exactly that number of times. (In theory, such a change might even slightly improve performance if the driver uses Perl threads to fill the buffer in the background.)

  • size() doesn't need to exhaust the result stream. It only needs to detach it. The official drivers don't have size(), so we're free to redefine it in order to make it more useful to Perl users.

  • Jolt: maybe check if for DELETE requests, accepting only Jolt yields an octet-stream response that contains JSON; if so, perhaps add to #12644 report

Neo4j::Driver::ResultSummary

  • Add timers to Neo4j::Driver::ResultSummary (see Neo4j::Bolt). Method names should be result_available_after and result_consumed_after, both returning milliseconds with a default of -1 when unavailable (HTTP).

  • Recent Neo4j versions have added database.

Neo4j::Driver::SummaryCounters

  • use Class::Accessor::Fast 0.34;

  • It seems Neo4j 4 added new counters for system updates. These are contains_system_updates and system_updates, the latter returning the number of system updates. Neither is available in Neo4j::Bolt 0.4201 according to the docs; need to check source.

Neo4j::Driver::Net

  • As a micro-optimisation for the HTTP net adapter API, it could be guaranteed for the http_header() method that the returned hashref will not be used by the driver/controller after the next call to request(), so that the underlying hash may be reused by the net adapter.

Neo4j::Driver::Net::Bolt

Neo4j::Driver::Net::HTTP

  • A small memory leak exists in new(). Probably no big deal. The config rework will eventually address this.

  • Perl HTTP libraries like LWP don't report OS errno codes. (BSD: man 2 intro) $! is unreliable. It might be possible to recreate errno codes by parsing error string messages. mentalisttraceur/errnoname might be of some use there. But this idea is very likely not worth the effort.

Neo4j::Driver::Net::HTTP::LWP

  • Consider externalsing this as a distribution of its own now rather than later. Eventually we might get rid of this new dependency by including an all-new adapter for HTTP::Tiny. Even before then, this new structure will make more clear that the driver in principle supports other backends besides just LWP.

Neo4j::Driver::Type::*

  • The eq and ne operators should be overloaded to allow for ID comparison on nodes and relationships.

  • Consider whether to use use overload '%{}' to allow direct access to e. g. properties using the pre-0.13 hashref syntax. See https://metacpan.org/pod/overload#Two-face-References for an example. perltie might perhaps also work. Note that overload might be a memory hog; see "BUGS" in Types::Serialiser.

  • Add property() as alias for get() in Neo4j::Driver::Type::Node and Neo4j::Driver::Type::Relationship, enabling clients to avoid the possibly confusing $record->get->get pattern. Another way to avoid this pattern would be $record->get->properties->{}. Aside from being longer, this is also 50 % slower because of the defensive copy that needs to be created. We should probably cache that one at least. In the long run, the internal representation of these types will change; the properties() hash ref will then actually be the fastest way to get a single property (about 8% faster than get()).