On Sunday 05 Jun 2011 03:29:42 Thomas Bruderer wrote: > I try (again) to update my .NET FCP2 library to the current state of > development. > > I do not even expect that a rare Message is documented correctly, but > something as essential as "PersistentGet" should be at least in a usable > state, shouldnt it?
IMHO PersistentGet is a "rare message". That is, most clients don't use persistent requests. > > A protocol should rarely change, especially a client protocol. But its > in constant change and some of the messages even have dynamic parameters > of course completley undocumented! > > If FCP shows anything of the development of the rest of the core, I am > really happy I never looked at that code in deep! > > Anyway from the documentation: > > PersistentGet as an example Lists 3 Arguments which are not sent by the > protocol anymore: > > /FileName/, /TempFilename/, /ClientToken/, not that any of these > parameters are ever described, but even the message in the wiki is still > the same since April 2010. And it doesnt help that you refer to the > source code, source code is NO DOCUMENTATION! its really desastrous that > you expose complete datastructures directly into the protocol, it makes > it MUCH too easy to change the FCP, and it looks like there are a lot of > people changing these strucutres constantly. ClientToken is still valid but it is only added if there is a ClientToken. Filename and TempFilename are only added if the download is to disk (and not if it is to temp space). > > In the meanwhile there are obviously 5 new undocumented fields in it.... > > /Started/, /Persistence/, /MaxSize/, /Identifier/, /Binary Blob/: most > of these are now documented at least in the Call, and the removal of the > ClientToken is certainly a good idea HOWEVER!!! ITS NOT DOCUMENTED!... Sorry about Persistence, we renamed PersistenceType to Persistence ages ago. > > In the ClientGet-Documentation there is still the field "ClientToken" > described as Returned in PersistentGet > <http://new-wiki.freenetproject.org/FCPv2/PersistentGet>, a hint to the > client, so the client doesn't need to maintain its own state. [FIXME: > how does this differ from Identifier?] ... > > You change the protocol permanently but have not even the time to send a > message back, OH I am sorry, I do not understand that parameter, maybe > its out of date? The ClientToken is a convenience feature so that an application can associate an arbitrary string with a download. It can use this to store its own state e.g. what it wants to do with the download when it's finished. It is optional. > > There needs to be a versioning of the protocol, its impossible to keep > track of all the source changes you do, and you should not expose > datastructures directly to the client interface, this is a very poor > design and makes impossible to support FCP2. This is not FCP2 this is at > least FCP2.0.174 Your library should be capable of ignoring any fields it doesn't recognise. Much of the point of using a text-based protocol is it's easy to extend. We don't eliminate existing fields without a very good reason however. > > There need to be a review process, if you change the protocol - there > must be a reason for that and not just conveniance, and the reason needs > documentation. If you change anything in the FCP it should get a new > protocol number and any change needs to be documented. If you do not > invest 10 - 20% of development time for documentation, you do something > wrong! I have no idea where you get the idea that PersistentGet has changed dramatically from. AFAICS it has changed very little, certainly over the last year. > > There is too much development going on and not enough planning > documenting, hack something together, deploy and use all the users as > testers... > > I won't get into general Project Planning - if there is one, but the FCP > is a reference for the outside, and it shows mainly incomeptence in a > great degree. > The main page still links to the old wiki, the new wiki is not used at > all, there is not a single wiki-commit for the fcp in the last 30 days. > > Regards, > Thomas Bruderer, Apophis > Okay if you're gonna be rude I'll look it up. PersistentGet was last modified on Thursday October 22nd *2009*. I agree the documentation is less than perfect. But PersistentGet is a fairly obscure feature, we hardly ever remove fields from FCP, and new fields are easy to ignore. So I really don't see a problem. Also I don't see that we are exposing internal structure here either. -------------- next part -------------- A non-text attachment was scrubbed... Name: signature.asc Type: application/pgp-signature Size: 198 bytes Desc: This is a digitally signed message part. URL: <https://emu.freenetproject.org/pipermail/devl/attachments/20110607/3810d764/attachment.pgp>
